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
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
|
<!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: The HDF5 File</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('_h5_f__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">
<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">The HDF5 File</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="sec_file"></a>
The HDF5 File</h1>
<h2><a class="anchor" id="subsec_file_intro"></a>
Introduction</h2>
<p>The purpose of this chapter is to describe how to work with HDF5 data files.</p>
<p>If HDF5 data is to be written to or read from a file, the file must first be explicitly created or opened with the appropriate file driver and access privileges. Once all work with the file is complete, the file must be explicitly closed.</p>
<p>This chapter discusses the following: </p><ul>
<li>File access modes </li>
<li>Creating, opening, and closing files </li>
<li>The use of file creation property lists </li>
<li>The use of file access property lists </li>
<li>The use of low-level file drivers</li>
</ul>
<p>This chapter assumes an understanding of the material presented in the data model chapter. For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_h5_d_m__u_g.html#sec_data_model">The HDF5 Data Model and File Structure</a>.</dd></dl>
<h2><a class="anchor" id="subsec_file_access_modes"></a>
File Access Modes</h2>
<p>There are two issues regarding file access: </p><ul>
<li>
What should happen when a new file is created but a file of the same name already exists? Should the create action fail, or should the existing file be overwritten? </li>
<li>
Is a file to be opened with read-only or read-write access?</li>
</ul>
<p>Four access modes address these concerns. Two of these modes can be used with <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a>, and two modes can be used with <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a>. </p><ul>
<li><a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> accepts <a class="el" href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</a> or <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> </li>
<li><a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> accepts <a class="el" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a> or <a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a></li>
</ul>
<p>The access modes are described in the table below.</p>
<table class="doxtable">
<caption>Access flags and modes</caption>
<tr>
<th>Access Flag </th><th>Resulting Access Mode </th></tr>
<tr>
<td><a class="el" href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</a> </td><td>If the file already exists, <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> fails. If the file does not exist, it is created and opened with read-write access. (Default) </td></tr>
<tr>
<td><a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> </td><td>If the file already exists, the file is opened with read-write access, and new data will overwrite any existing data. If the file does not exist, it is created and opened with read-write access. </td></tr>
<tr>
<td><a class="el" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a> </td><td>An existing file is opened with read-only access. If the file does not exist, <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> fails. (Default) </td></tr>
<tr>
<td><a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a> </td><td>An existing file is opened with read-write access. If the file does not exist, <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> fails. </td></tr>
</table>
<p>By default, <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> opens a file for read-only access; passing <a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a> allows read-write access to the file.</p>
<p>By default, <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> fails if the file already exists; only passing <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> allows the truncating of an existing file.</p>
<h2><a class="anchor" id="subsec_file_creation_access"></a>
File Creation and File Access Properties</h2>
<p>File creation and file access property lists control the more complex aspects of creating and accessing files.</p>
<p>File creation property lists control the characteristics of a file such as the size of the userblock, a user-definable data block; the size of data address parameters; properties of the B-trees that are used to manage the data in the file; and certain HDF5 Library versioning information.</p>
<p>For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="#subsubsec_file_property_lists_props">File Creation Properties</a>.</dd></dl>
<p>This section has a more detailed discussion of file creation properties. If you have no special requirements for these file characteristics, you can simply specify <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> for the default file creation property list when a file creation property list is called for.</p>
<p>File access property lists control properties and means of accessing a file such as data alignment characteristics, metadata block and cache sizes, data sieve buffer size, garbage collection settings, and parallel I/O. Data alignment, metadata block and cache sizes, and data sieve buffer size are factors in improving I/O performance.</p>
<p>For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="#subsubsec_file_property_lists_access">File Access Properties</a>.</dd></dl>
<p>This section has a more detailed discussion of file access properties. If you have no special requirements for these file access characteristics, you can simply specify <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> for the default file access property list when a file access property list is called for.</p>
<table class="doxtable">
<caption>Figure 10 - More sample file structures</caption>
<tr>
<td><div class="image">
<img src="UML_FileAndProps.gif" alt=""/>
<div class="caption">
UML model for an HDF5 file and its property lists</div></div>
</td></tr>
</table>
<h2><a class="anchor" id="subsec_file_drivers"></a>
Low-level File Drivers</h2>
<p>The concept of an HDF5 file is actually rather abstract: the address space for what is normally thought of as an HDF5 file might correspond to any of the following at the storage level: </p><ul>
<li>Single file on a standard file system </li>
<li>Multiple files on a standard file system </li>
<li>Multiple files on a parallel file system </li>
<li>Block of memory within an application's memory space </li>
<li>More abstract situations such as virtual files</li>
</ul>
<p>This HDF5 address space is generally referred to as an HDF5 file regardless of its organization at the storage level.</p>
<p>HDF5 accesses a file (the address space) through various types of low-level file drivers. The default HDF5 file storage layout is as an unbuffered permanent file which is a single, contiguous file on local disk. Alternative layouts are designed to suit the needs of a variety of systems, environments, and applications.</p>
<h2><a class="anchor" id="subsec_file_program_model"></a>
Programming Model for Files</h2>
<p>Programming models for creating, opening, and closing HDF5 files are described in the sub-sections below.</p>
<h3><a class="anchor" id="subsubsec_file_program_model_create"></a>
Creating a New File</h3>
<p>The programming model for creating a new HDF5 file can be summarized as follows: </p><ul>
<li>Define the file creation property list </li>
<li>Define the file access property list </li>
<li>Create the file</li>
</ul>
<p>First, consider the simple case where we use the default values for the property lists. See the example below.</p>
<p><em>Creating an HDF5 file using property list defaults</em> </p><div class="fragment"><div class="line">file_id = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a> (<span class="stringliteral">"SampleFile.h5"</span>, <a class="code hl_define" href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</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="ttc" id="a_h5_fpublic_8h_html_a7a47250dc1435705233dca7297ba3d90"><div class="ttname"><a href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</a></div><div class="ttdeci">#define H5F_ACC_EXCL</div><div class="ttdef"><b>Definition</b> H5Fpublic.h:51</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="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><!-- fragment --><p>Note: The example above specifies that <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> should fail if SampleFile.h5 already exists.</p>
<p>A more complex case is shown in the example below. In this example, we define file creation and access property lists (though we do not assign any properties), specify that <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> should fail if SampleFile.h5 already exists, and create a new file named SampleFile.h5. The example does not specify a driver, so the default driver, <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>, will be used.</p>
<p><em>Creating an HDF5 file using property lists</em> </p><div class="fragment"><div class="line">fcplist_id = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a> (<a class="code hl_define" href="_h5_ppublic_8h.html#a206f334f1e6c973e1215a3148b45b977">H5P_FILE_CREATE</a>)</div>
<div class="line"><...set desired file creation properties...></div>
<div class="line">faplist_id = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a> (<a class="code hl_define" href="_h5_ppublic_8h.html#a60ec2d4334addfc0eda89614598ee38e">H5P_FILE_ACCESS</a>)</div>
<div class="line"><...set desired file access properties...></div>
<div class="line">file_id = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a> (<span class="stringliteral">"SampleFile.h5"</span>, <a class="code hl_define" href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</a>, fcplist_id, faplist_id)</div>
<div class="ttc" id="a_h5_ppublic_8h_html_a206f334f1e6c973e1215a3148b45b977"><div class="ttname"><a href="_h5_ppublic_8h.html#a206f334f1e6c973e1215a3148b45b977">H5P_FILE_CREATE</a></div><div class="ttdeci">#define H5P_FILE_CREATE</div><div class="ttdef"><b>Definition</b> H5Ppublic.h:51</div></div>
<div class="ttc" id="a_h5_ppublic_8h_html_a60ec2d4334addfc0eda89614598ee38e"><div class="ttname"><a href="_h5_ppublic_8h.html#a60ec2d4334addfc0eda89614598ee38e">H5P_FILE_ACCESS</a></div><div class="ttdeci">#define H5P_FILE_ACCESS</div><div class="ttdef"><b>Definition</b> H5Ppublic.h:52</div></div>
<div class="ttc" id="agroup___p_l_c_r_html_gaf1b11da01d4d45d788c45f8bc5f0cbfa"><div class="ttname"><a href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a></div><div class="ttdeci">hid_t H5Pcreate(hid_t cls_id)</div><div class="ttdoc">Creates a new property list as an instance of a property list class.</div></div>
</div><!-- fragment --><p> Notes:</p><ol type="1">
<li>A root group is automatically created in a file when the file is first created.</li>
<li>File property lists, once defined, can be reused when another file is created within the same application.</li>
</ol>
<h3><a class="anchor" id="subsubsec_file_program_model_open"></a>
Opening an Existing File</h3>
<p>The programming model for opening an existing HDF5 file can be summarized as follows: </p><ul>
<li>
Define or modify the file access property list including a low-level file driver (optional) </li>
<li>
Open the file</li>
</ul>
<p>The code in the example below shows how to open an existing file with read-only access.</p>
<p><em>Opening an HDF5 file</em> </p><div class="fragment"><div class="line">faplist_id = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a> (<a class="code hl_define" href="_h5_ppublic_8h.html#a60ec2d4334addfc0eda89614598ee38e">H5P_FILE_ACCESS</a>)</div>
<div class="line">status = <a class="code hl_function" href="group___f_a_p_l.html#ga77f0643117835e7f7992d573761b5052">H5Pset_fapl_stdio</a> (faplist_id)</div>
<div class="line">file_id = <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a> (<span class="stringliteral">"SampleFile.h5"</span>, <a class="code hl_define" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a>, faplist_id)</div>
<div class="ttc" id="a_h5_fpublic_8h_html_a1c406ffa89f4acf5a332144a2683d394"><div class="ttname"><a href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a></div><div class="ttdeci">#define H5F_ACC_RDONLY</div><div class="ttdef"><b>Definition</b> H5Fpublic.h:48</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_ga77f0643117835e7f7992d573761b5052"><div class="ttname"><a href="group___f_a_p_l.html#ga77f0643117835e7f7992d573761b5052">H5Pset_fapl_stdio</a></div><div class="ttdeci">herr_t H5Pset_fapl_stdio(hid_t fapl_id)</div><div class="ttdoc">Sets the standard I/O driver.</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_file_program_model_close"></a>
Closing a File</h3>
<p>The programming model for closing an HDF5 file is very simple: </p><ul>
<li>Close file</li>
</ul>
<p>We close SampleFile.h5 with the code in the example below.</p>
<p><em>Closing an HDF5 file</em> </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a> (file_id)</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><!-- fragment --><p> Note that <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> flushes all unwritten data to storage and that file_id is the identifier returned for SampleFile.h5 by <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a>.</p>
<p>More comprehensive discussions regarding all of these steps are provided below.</p>
<h2><a class="anchor" id="subsec_file_h5dump"></a>
Using h5dump to View a File</h2>
<p>h5dump is a command-line utility that is included in the HDF5 distribution. This program provides a straight-forward means of inspecting the contents of an HDF5 file. You can use h5dump to verify that a program is generating the intended HDF5 file. h5dump displays ASCII output formatted according to the HDF5 DDL grammar.</p>
<p>The following h5dump command will display the contents of SampleFile.h5: </p><div class="fragment"><div class="line">h5dump SampleFile.h5</div>
</div><!-- fragment --><p>If no datasets or groups have been created in and no data has been written to the file, the output will look something like the following: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"SampleFile.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><p>Note that the root group, indicated above by /, was automatically created when the file was created.</p>
<p>h5dump is described on the <a href="https://portal.hdfgroup.org/display/HDF5/h5dump">Tools</a> page under <a href="https://portal.hdfgroup.org/display/HDF5/Libraries+and+Tools+Reference">Libraries and Tools Reference</a>. The HDF5 DDL grammar is described in the document <a class="el" href="_d_d_l_b_n_f110.html">DDL in BNF through HDF5 1.10</a>.</p>
<h2><a class="anchor" id="subsec_file_summary"></a>
File Function Summaries</h2>
<p>General library (<a class="el" href="group___h5.html">Library General (H5)</a> functions and macros), (<a class="el" href="group___h5_f.html">Files (H5F)</a> functions), file related (<a class="el" href="group___h5_p.html">Property Lists (H5P)</a> functions), and file driver (<a class="el" href="group___h5_p.html">Property Lists (H5P)</a> functions) are listed below.</p>
<table class="doxtable">
<caption>General library functions and macros</caption>
<tr>
<th>Function </th><th>Purpose </th></tr>
<tr>
<td><a class="el" href="group___h5.html#ga93525482e1168344f4c92470f99d88be" title="Verifies that HDF5 library versions are consistent.">H5check_version</a> </td><td>Verifies that HDF5 library versions are consistent. </td></tr>
<tr>
<td><a class="el" href="group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574" title="Flushes all data to disk, closes all open objects, and releases memory.">H5close</a> </td><td>Flushes all data to disk, closes all open identifiers, and cleans up memory. </td></tr>
<tr>
<td><a class="el" href="group___h5.html#ga7f80eb63b5e78812b9d0d50ac46764e8" title="Instructs library not to install atexit() cleanup routine.">H5dont_atexit</a> </td><td>Instructs the library not to install the atexit cleanup routine. </td></tr>
<tr>
<td><a class="el" href="group___h5.html#gae511943bcb837a52a012a3a5dd7b90ef" title="Garbage collects on all free-lists of all types.">H5garbage_collect</a> </td><td>Performs garbage collection (GC) on all free-lists of all types. </td></tr>
<tr>
<td><a class="el" href="group___h5.html#gaf87da966fdf896ec7bca794e21d4ab0a" title="Returns the HDF library release number.">H5get_libversion</a> </td><td>Returns the HDF library release number. </td></tr>
<tr>
<td><a class="el" href="group___h5.html#ga27fa33dc262dda95c5aa8df533837480" title="Initializes the HDF5 library.">H5open</a> </td><td>Initializes the HDF5 library. </td></tr>
<tr>
<td><a class="el" href="group___h5.html#gaa3f78b24b8a1ff4168db2b7ddca21545" title="Sets free-list size limits.">H5set_free_list_limits</a> </td><td>Sets free-list size limits. </td></tr>
<tr>
<td><a class="el" href="_h5public_8h.html#aa80cec001d4154b554aa2b0b6223a7f3" title="Determines whether the version of the library being used is greater than or equal to the specified ve...">H5_VERSION_GE</a> </td><td>Determines whether the version of the library being used is greater than or equal to the specified version. </td></tr>
<tr>
<td><a class="el" href="_h5public_8h.html#acc311aa4fed2832a44c4bb93f2625043" title="Determines whether the version of the library being used is less than or equal to the specified versi...">H5_VERSION_LE</a> </td><td>Determines whether the version of the library being used is less than or equal to the specified version. </td></tr>
</table>
<table class="doxtable">
<caption>File functions </caption>
<tr>
<th>Function </th><th>Purpose </th></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gafcc153d8606829d4401e93305e5246d7" title="Clears the external link open file cache.">H5Fclear_elink_file_cache</a> </td><td>Clears the external link open file cache for a file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> </td><td>Closes HDF5 file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> </td><td>Creates new HDF5 file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gae686870f0a276c4d06bbc667b2c24124" title="Flushes all buffers associated with a file to storage.">H5Fflush</a> </td><td>Flushes data to HDF5 file on storage medium. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga359585c49f82f5199178777b39e780f4" title="Returns a file access property list identifier.">H5Fget_access_plist</a> </td><td>Returns a file access property list identifier. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga2f823a9e929b00b06a6be80619a61778" title="Returns a file creation property list identifier.">H5Fget_create_plist</a> </td><td>Returns a file creation property list identifier. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gadc53f4e76b1199cb5d2a8cb7fbb114ad" title="Retrieves a copy of the image of an existing, open file.">H5Fget_file_image</a> </td><td>Retrieves a copy of the image of an existing, open file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga515426821321c261a825b4e4a3f576fe" title="Returns the size of an HDF5 file (in bytes)">H5Fget_filesize</a> </td><td>Returns the size of an HDF5 file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga3ef2673183567543346668a8f1eca2e9" title="Returns the amount of free space in a file (in bytes)">H5Fget_freespace</a> </td><td>Returns the amount of free space in a file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gae17036b3e36a8777328204e8bf073144">H5Fget_info</a> </td><td>Returns global information for a file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga466179d7783d256329c2e3110055a16c" title="Determines the read/write or read-only status of a file.">H5Fget_intent</a> </td><td>Determines the read/write or read-only status of a file. </td></tr>
<tr>
<td><a class="el" href="group___m_d_c.html#gaa67f127242d4aaf244ae8ac4a1fe6a59" title="Obtains current metadata cache configuration for target file.">H5Fget_mdc_config</a> </td><td>Obtains current metadata cache configuration for target file. </td></tr>
<tr>
<td><a class="el" href="group___m_d_c.html#gabea066c3fd924d2cf868ecee66a7c41f" title="Obtains target file's metadata cache hit rate.">H5Fget_mdc_hit_rate</a> </td><td>Obtains target file's metadata cache hit rate. </td></tr>
<tr>
<td><a class="el" href="group___m_d_c.html#gacda6cbd60d3c50b59f801eba4e5a335f" title="Obtains current metadata cache size data for specified file.">H5Fget_mdc_size</a> </td><td>Obtains current metadata cache size data for specified file. </td></tr>
<tr>
<td><a class="el" href="group___p_h5_f.html#ga849316b77788799fecb321a87d987ade" title="Retrieves the atomicity mode in use.">H5Fget_mpi_atomicity</a> </td><td>Retrieves the atomicity mode in use. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga0ed43dbe476a160b73f55127c7db797c" title="Retrieves name of file to which object belongs.">H5Fget_name</a> </td><td>Retrieves the name of the file to which the object belongs. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gadcdae0aca7c88064db0d32de7f1e31f2" title="Returns the number of open object identifiers for an open file.">H5Fget_obj_count</a> </td><td>Returns the number of open object identifiers for an open file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga35e72579bd07433162b80ddc0bd0c5b1" title="Returns a list of open object identifiers.">H5Fget_obj_ids</a> </td><td>Returns a list of open object identifiers. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gae4020a66fb8da0586e3b74c81ffccea4" title="Returns pointer to the file handle from the virtual file driver.">H5Fget_vfd_handle</a> </td><td>Returns pointer to the file handle from the virtual file driver. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga6055c2ea3438bd4aaf221eba66843225" title="Determines whether a file is in the HDF5 format.">H5Fis_hdf5</a> </td><td>Determines whether a file is in the HDF5 format. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b" title="Mounts an HDF5 file.">H5Fmount</a> </td><td>Mounts a file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> </td><td>Opens an existing HDF5 file. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#ga3f213eb05c5419d63ba168c30036e47b" title="Returns a new identifier for a previously-opened HDF5 file.">H5Freopen</a> </td><td>Returns a new identifier for a previously-opened HDF5 file. </td></tr>
<tr>
<td><a class="el" href="group___m_d_c.html#ga6708886c2bb8740327d9078d7840197f" title="Resets hit rate statistics counters for the target file.">H5Freset_mdc_hit_rate_stats</a> </td><td>Resets hit rate statistics counters for the target file. </td></tr>
<tr>
<td><a class="el" href="group___m_d_c.html#ga81bc06be69131484eb04d01511b9c8f8" title="Attempts to configure metadata cache of target file.">H5Fset_mdc_config</a> </td><td>Configures metadata cache of target file. </td></tr>
<tr>
<td><a class="el" href="group___p_h5_f.html#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity</a> </td><td>Sets the MPI atomicity mode. </td></tr>
<tr>
<td><a class="el" href="group___h5_f.html#gae8f807d3f04a33f132ffb6c5295e897f" title="Unounts an HDF5 file.">H5Funmount</a> </td><td>Unmounts a file. </td></tr>
</table>
<p><a class="anchor" id="fcpl_table_tag"></a>File creation property list functions (H5P) </p><div></div><div> <a class="anchor" id="table_fcpl_id"></a>
<table class="doxtable">
<caption border="1" style="background-color:whitesmoke;">File creation property list functions (H5P)</caption>
<tr>
<th>Function </th><th>Purpose </th></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga403bd982a2976c932237b186ed1cff4d" title="Sets user block size.">H5Pset_userblock</a>/<a class="el" href="group___f_c_p_l.html#ga75b312bb0c70419fc428d743a65bed86" title="Retrieves the size of a user block.">H5Pget_userblock</a> </td><td>Sets/retrieves size of userblock. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#gae5eb3ba16f063d151d1b56d33e0710a9" title="Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.">H5Pset_sizes</a>/<a class="el" href="group___f_c_p_l.html#ga8da25b0367cf226c2888141661fd7a2d" title="Retrieves the size of the offsets and lengths used in an HDF5 file.">H5Pget_sizes</a> </td><td>Sets/retrieves byte size of offsets and lengths used to address objects in HDF5 file. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga444ca905f084f9f96b7fe60d2a8c8176">H5Pset_sym_k</a>/<a class="el" href="group___f_c_p_l.html#ga1d4ee26c030ced6d7a314543578c88b1" title="Retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size.">H5Pget_sym_k</a> </td><td>Sets/retrieves size of parameters used to control symbol table nodes. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga84a72f59d17841c37ab34674bf22a10c" title="Sets the size of the parameter used to control the B-trees for indexing chunked datasets.">H5Pset_istore_k</a>/<a class="el" href="group___f_c_p_l.html#ga2179b032be5d2efbca63d8f82a292ec1" title="Queries the 1/2 rank of an indexed storage B-tree.">H5Pget_istore_k</a> </td><td>Sets/retrieves size of parameter used to control B-trees for indexing chunked datasets. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#gad012d7f3c2f1e1999eb1770aae3a4963" title="Sets the file space page size for a file creation property list.">H5Pset_file_space_page_size</a>/<a class="el" href="group___f_c_p_l.html#gaab5e8c08e4f588e0af1d937fcebfc885" title="Retrieves the file space page size for a file creation property list.">H5Pget_file_space_page_size</a> </td><td>Sets or retrieves the file space page size used in paged aggregation and paged buffering. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga167ff65f392ca3b7f1933b1cee1b9f70" title="Sets the file space handling strategy and persisting free-space values for a file creation property l...">H5Pset_file_space_strategy</a>/<a class="el" href="group___f_c_p_l.html#ga54cf6ca4f897ba9ee3695a15fe8e6029" title="Retrieves the file space handling strategy, persisting free-space condition and threshold value for a...">H5Pget_file_space_strategy</a> </td><td>Sets or retrieves the file space handling strategy, the persisting free-space and the free-space section size. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga5e5020b1e2579da4617ea115e3cc50f1" title="Sets number of shared object header message indexes.">H5Pset_shared_mesg_nindexes</a>/<a class="el" href="group___f_c_p_l.html#ga30980db1814a251e7b40362af1006652" title="Retrieves the number of shared object header message indexes in file creation property list.">H5Pget_shared_mesg_nindexes</a> </td><td>Sets or retrieves number of shared object header message indexes in file creation property list. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga052aba0c1c5a3908a62335fc28e287ef" title="Configures the specified shared object header message index.">H5Pset_shared_mesg_index</a> </td><td>Configures the specified shared object header message index. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#gac6bac4446c45d348c953b3afdecede2c" title="Retrieves the configuration settings for a shared message index.">H5Pget_shared_mesg_index</a> </td><td>Retrieves the configuration settings for a shared message index. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga967f961f4002d63804dc67b3bcd8f354" title="Sets shared object header message storage phase change thresholds.">H5Pset_shared_mesg_phase_change</a>/<a class="el" href="group___f_c_p_l.html#gab013e791706b44f545a97096d8e4c72e" title="Retrieves shared object header message phase change information.">H5Pget_shared_mesg_phase_change</a> </td><td>Sets or retrieves shared object header message storage phase change thresholds. </td></tr>
<tr>
<td><a class="el" href="group___f_c_p_l.html#ga99c0afbb68e8e775ae70cac44404a534" title="Retrieves the version information of various objects for a file creation property list(deprecated)">H5Pget_version</a> </td><td></td></tr>
</table>
</div><div> </div><p><a class="anchor" id="fapl_table_tag"></a>File access property list functions (H5P) </p><div></div><div> <a class="anchor" id="table_fapl_id"></a>
<table class="doxtable">
<caption border="1" style="background-color:whitesmoke;">File access property list functions (H5P)</caption>
<tr>
<th>Function </th><th>Purpose </th></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gab99d5af749aeb3896fd9e3ceb273677a" title="Sets alignment properties of a file access property list.">H5Pset_alignment</a>/<a class="el" href="group___f_a_p_l.html#ga6735afde382cfd746b92a1a3b0e6a2ab" title="Retrieves the current settings for alignment properties from a file access property list.">H5Pget_alignment</a> </td><td>Sets/retrieves alignment properties. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache</a>/<a class="el" href="group___f_a_p_l.html#ga9481a0b08d729ec68897d57db1827861" title="Queries the raw data chunk cache parameters.">H5Pget_cache</a> </td><td>Sets/retrieves metadata cache and raw data chunk cache parameters. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga237e300b96222a259896b24cf52405b0" title="Sets write tracking information for core driver, H5FD_CORE.">H5Pset_core_write_tracking</a>/<a class="el" href="group___f_a_p_l.html#ga60ec714459a4911d28e46deb201f4f2e" title="Gets information about the write tracking feature used by the core VFD.">H5Pget_core_write_tracking</a> </td><td>Sets/retrieves write tracking information for core driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gac21a815e9b133802df625c9f766ef325" title="Sets the number of files that can be held open in an external link open file cache.">H5Pset_elink_file_cache_size</a>/<a class="el" href="group___f_a_p_l.html#ga4c9bcfff90f48bfefa2c25e551485923" title="Retrieves the size of the external link open file cache.">H5Pget_elink_file_cache_size</a> </td><td>Sets/retrieves the size of the external link open file cache from the specified file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gaa44cc0e592608e12082dad9305b3c74d" title="Controls the library's behavior of evicting metadata associated with a closed object.">H5Pset_evict_on_close</a>/<a class="el" href="group___f_a_p_l.html#ga12789fcfeaea073c13202e6401f404a6" title="Retrieves the file access property list setting that determines whether an HDF5 object will be evicte...">H5Pget_evict_on_close</a> </td><td>Set/get the file access property list setting that determines whether an HDF5 object will be evicted from the library's metadata cache when it is closed. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga61f01a12d5392ccf1321168f3c28f36f" title="Sets garbage collecting references flag.">H5Pset_gc_references</a>/<a class="el" href="group___f_a_p_l.html#gaaa81d8427b419d80eff6e1d216d99b71" title="Returns garbage collecting references setting.">H5Pget_gc_references</a> </td><td>Sets/retrieves garbage collecting references flag. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga6b24e6daf4816bbfb89b63bab40aa982" title="Sets offset property for low-level access to a file in a family of files.">H5Pset_family_offset</a> </td><td>Sets offset property for low-level access to a file in a family of files. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga14977eaaf6565ba871b575de3163f1b3" title="Retrieves a data offset from the file access property list.">H5Pget_family_offset</a> </td><td>Retrieves a data offset from the file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga60e3567f677fd3ade75b909b636d7b9c" title="Sets the file close degree.">H5Pset_fclose_degree</a>/<a class="el" href="group___f_a_p_l.html#ga41da04bb4f823ba9f7d6c57dc8fe2878" title="Returns the file close degree.">H5Pget_fclose_degree</a> </td><td>Sets/retrieves file close degree property. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga31d0299f6ad287e013b2a02a8ccc1fa2" title="Sets an initial file image in a memory buffer.">H5Pset_file_image</a> </td><td>Sets an initial file image in a memory buffer. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga337626cc516d5d1e3303ea6bc350e56b" title="Retrieves a copy of the file image designated as the initial content and structure of a file.">H5Pget_file_image</a> </td><td>Retrieves a copy of the file image designated as the initial content and structure of a file. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks</a>/<a class="el" href="group___f_a_p_l.html#gae17e38082dfdbadd75c897f1e6a9096e" title="Retrieves callback routines for working with file images.">H5Pget_file_image_callbacks</a> </td><td>Sets/gets the callbacks for working with file images. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga503e9ff6121a67cf53f8b67054ed9391" title="Sets the file locking property values.">H5Pset_file_locking</a>/<a class="el" href="group___f_a_p_l.html#ga5de19a5a8ac23ca417aa2d49d708dc2d" title="Retrieves the file locking property values.">H5Pget_file_locking</a> </td><td>Sets/retrieves file locking property values. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga8822e3dedc8e1414f20871a87d533cb1" title="Sets the minimum metadata block size.">H5Pset_meta_block_size</a>/<a class="el" href="group___f_a_p_l.html#gac17861181246af0209c0da5209305461" title="Returns the current metadata block size setting.">H5Pget_meta_block_size</a> </td><td>Sets the minimum metadata blocksize or retrieves the current metadata block size setting. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gab827cef16ec569c87cec94a8b3f350c5" title="Sets the number of read attempts in a file access property list.">H5Pset_metadata_read_attempts</a>/<a class="el" href="group___f_a_p_l.html#ga670948d56435920f1e1c2e88b823935e" title="Retrieves the number of read attempts from a file access property list.">H5Pget_metadata_read_attempts</a> </td><td>Sets/gets the number of read attempts from a file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gaf234199ad4cf9c708f45893f7f9cd4d3" title="Set the initial metadata cache configuration in the indicated File Access Property List to the suppli...">H5Pset_mdc_config</a>/<a class="el" href="group___f_a_p_l.html#ga3012f7f3310c7d25ada7617896bef1ee" title="Get the current initial metadata cache configuration from the provided file access property list.">H5Pget_mdc_config</a> </td><td>Set/get the initial metadata cache configuration in the indicated file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga65cf9fea33d1324009efc2d5db848434" title="Sets the metadata cache image option for a file access property list.">H5Pset_mdc_image_config</a>/<a class="el" href="group___f_a_p_l.html#gaaa18d59ee9efb12626410b1638f76f00" title="Retrieves the metadata cache image configuration values for a file access property list.">H5Pget_mdc_image_config</a> </td><td>Set/get the metadata cache image option for a file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga4d7206c5679d7243410058eceae59b2c" title="Sets metadata cache logging options.">H5Pset_mdc_log_options</a>/<a class="el" href="group___f_a_p_l.html#gaa3a1ca6e294cc5074933239cc3d0e4a3" title="Gets metadata cache logging options.">H5Pget_mdc_log_options</a> </td><td>Set/get the metadata cache logging options. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga507341f31848c57008a3225bff3fe128" title="Specifies type of data to be accessed via the MULTI driver, enabling more direct access.">H5Pset_multi_type</a>/<a class="el" href="group___f_a_p_l.html#ga251515e9fee4641037b4866a4f7c49fe" title="Retrieves type of data property for MULTI driver.">H5Pget_multi_type</a> </td><td>Sets/gets the type of data property for the MULTI driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gab4a4a788af5b6e88381dda0df2efbf19" title="Sets a callback function to invoke when an object flush occurs in the file.">H5Pset_object_flush_cb</a>/<a class="el" href="group___f_a_p_l.html#gadb66d434fd8d2f600213b0eec539564e" title="Retrieves the object flush property values from the file access property list.">H5Pget_object_flush_cb</a> </td><td>Set/get the object flush property values from the file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga8008cddafa81bd1ddada23f6d9a161ca" title="Sets the maximum size for the page buffer and the minimum percentage for metadata and raw data pages.">H5Pset_page_buffer_size</a>/<a class="el" href="group___f_a_p_l.html#ga0da11baf31cf424d053aa7952c933d98" title="Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data p...">H5Pget_page_buffer_size</a> </td><td>Set/get the maximum size for the page buffer. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga24fd737955839194bf5605d5f47928ee" title="Sets the maximum size of the data sieve buffer.">H5Pset_sieve_buf_size</a>/<a class="el" href="group___f_a_p_l.html#gac2321d0c34bb2b3cf33cd7bf02ca8e66" title="Returns maximum data sieve buffer size.">H5Pget_sieve_buf_size</a> </td><td>Sets/retrieves maximum size of data sieve buffer. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gacbe1724e7f70cd17ed687417a1d2a910" title="Controls the range of library release versions used when creating objects in a file.">H5Pset_libver_bounds</a> </td><td>Sets bounds on library versions, and indirectly format versions, to be used when creating objects. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gad5d7e671c3a06bcee64bc25841aaf607" title="Retrieves library version bounds settings that indirectly control the format versions used when creat...">H5Pget_libver_bounds</a> </td><td>Retrieves library version bounds settings that indirectly control the format versions used when creating objects. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga5a99962a79412814b79be830f14c23dd" title="Sets the size of a contiguous block reserved for small data.">H5Pset_small_data_block_size</a> </td><td>Sets the size of a contiguous block reserved for small data. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga6896bea06d7744b56e22347f572f5470" title="Retrieves the current small data block size setting.">H5Pget_small_data_block_size</a> </td><td>Retrieves the current small data block size setting. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga8aaa97e70b2544c3d95d908e1ae5b0f0" title="Set the file VOL connector for a file access property list.">H5Pset_vol</a> </td><td>Sets the file VOL connector for a file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga2ad4dc5c6e5e4271334a7b1c6ee0777d" title="Query the capability flags for the VOL connector that will be used with this file access property lis...">H5Pget_vol_cap_flags</a> </td><td>Retrieves the capability flags for the VOL connector that will be used with a file access property list. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga5f133bdf09ca5a32622688d1ba5cc838" title="Returns the identifier of the current VOL connector.">H5Pget_vol_id</a> </td><td>Retrieves the identifier of the current VOL connector. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gafc58db23c257cdcf2f0c1c3ae911ab0f" title="Returns a copy of the VOL information for a connector.">H5Pget_vol_info</a> </td><td>Retrieves a copy of the VOL information for a connector. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga6daceb4a9e51fca7cb198f964b67baf0" title="Set the MPI communicator and info.">H5Pset_mpi_params</a>/<a class="el" href="group___f_a_p_l.html#ga5554cf0775f9d7ac3b0cd844533d4486" title="Get the MPI communicator and info.">H5Pget_mpi_params</a> </td><td>Sets/retrieves the MPI communicator and info. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga6380f9929cf42c8203813f7e72dde35c" title="Sets metadata write mode to be collective or independent (default)">H5Pset_coll_metadata_write</a>/<a class="el" href="group___f_a_p_l.html#gac83ab4e788a5b6e0d578f40ca67d8d00" title="Retrieves metadata write mode setting.">H5Pget_coll_metadata_write</a> </td><td>Sets/retrieves metadata write mode setting. </td></tr>
</table>
</div><div> </div><p><a class="anchor" id="fd_pl_table_tag"></a>File driver property list functions (H5P) </p><div></div><div> <a class="anchor" id="table_fd_pl_id"></a>
<table class="doxtable">
<caption border="1" style="background-color:whitesmoke;">File driver property list functions (H5P)</caption>
<tr>
<th>Function </th><th>Purpose </th></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga8bcce60e23e9d2a019212c63b146502e" title="Sets a file driver.">H5Pset_driver</a> </td><td>Sets a file driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga43a733fe9723dd15f5ad7abda909a1b8" title="Returns low-lever driver identifier.">H5Pget_driver</a> </td><td>Returns the identifier for the driver used to create a file. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga1b072297fed53cd8586604e45c483a56" title="Returns a pointer to file driver information.">H5Pget_driver_info</a> </td><td>Returns a pointer to file driver information. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga156702db27ece40d21b37be5fe5e8b15" title="Sets a file driver according to a given driver name.">H5Pset_driver_by_name</a> </td><td>Sets a file driver according to a given driver name. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gac4426b1d36aa8766fbe2deaf67a18c06" title="Sets a file driver according to a given driver value (ID).">H5Pset_driver_by_value</a> </td><td>Sets a file driver according to a given driver value. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gac0d9eb573b84ce125433e81b2a475085" title="Retrieves a string representation of the configuration for the driver set on the given FAPL....">H5Pget_driver_config_str</a> </td><td>Retrieves a string representation of the configuration for the driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849" title="Modifies the file access property list to use the H5FD_CORE driver.">H5Pset_fapl_core</a>/<a class="el" href="group___f_a_p_l.html#gac347d401cbb28fecd78c5f15ddb4c9c1" title="Queries core file driver properties.">H5Pget_fapl_core</a> </td><td>Sets the driver for buffered memory files (in RAM) or retrieves information regarding the driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7" title="Sets up use of the direct I/O driver.">H5Pset_fapl_direct</a>/<a class="el" href="group___f_a_p_l.html#ga038e5f3952e49b6945039fc2b010ab16" title="Retrieves direct I/O driver settings.">H5Pget_fapl_direct</a> </td><td>Sets up use of the direct I/O driver or retrieves the direct I/O driver settings. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53" title="Sets the file access property list to use the family driver.">H5Pset_fapl_family</a>/<a class="el" href="group___f_a_p_l.html#ga0bc1a003f26bf4b53e4487b6ca117389" title="Returns file access property list information.">H5Pget_fapl_family</a> </td><td>Sets driver for file families, designed for systems that do not support files larger than 2 gigabytes, or retrieves information regarding driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga970d077c8e712a4692f43fa4f38dde14" title="Modifies the file access property list to use the H5FD_HDFS driver.">H5Pset_fapl_hdfs</a>/<a class="el" href="group___f_a_p_l.html#gae59e7d8e0e8823e6dd6034b66418ed00" title="Queries a File Access Property List for H5FD_HDFS file driver properties.">H5Pget_fapl_hdfs</a> </td><td>. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga714340ec9cbb65cb0a819e1d775825f0" title="Modifies the specified File Access Property List to use the H5FD_IOC driver.">H5Pset_fapl_ioc</a>/<a class="el" href="group___f_a_p_l.html#ga8482cdac1272818e4e0f86a665f8ef98" title="Queries a File Access Property List for H5FD_IOC file driver properties.">H5Pget_fapl_ioc</a> </td><td>Modifies/queries the file driver properties of the I/O concentrator driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga4e03be2fe83ed02b32266a6c81427beb" title="Sets up the logging virtual file driver (H5FD_LOG) for use.">H5Pset_fapl_log</a> </td><td>The logging driver is a clone of the standard SEC2 (<a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>) driver with additional facilities for logging metrics and activity to a file. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga8491676811ccc7ba582e30fb63da6563" title="Modifies the file access property list to use the H5FD_MIRROR driver.">H5Pset_fapl_mirror</a>/<a class="el" href="group___f_a_p_l.html#ga2c0636d9bb9c50d381afbd0d3140e593" title="Queries a File Access Property List for H5FD_MIRROR file driver properties.">H5Pget_fapl_mirror</a> </td><td>Modifies/queries the file driver properties of the mirror driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff" title="Stores MPI IO communicator information to the file access property list.">H5Pset_fapl_mpio</a>/<a class="el" href="group___f_a_p_l.html#ga5d9e4b9f27791ccf19484a898f3fd6fa" title="Returns MPI IO communicator information.">H5Pget_fapl_mpio</a> </td><td>Sets driver for files on parallel file systems (MPI I/O) or retrieves information regarding the driver. </td></tr>
<tr>
<td>H5Pset_fapl_mpiposix/H5Pget_fapl_mpiposix </td><td>No longer available. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58" title="Sets up use of the multi-file driver.">H5Pset_fapl_multi</a>/<a class="el" href="group___f_a_p_l.html#ga765b7880795a139f3b567743ac88c3c7" title="Returns information about the multi-file access property list.">H5Pget_fapl_multi</a> </td><td>Sets driver for multiple files, separating categories of metadata and raw data, or retrieves information regarding driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga4d053c7682e54287e550113972b7dda6" title="set the onion info for the file access property list">H5Pset_fapl_onion</a>/<a class="el" href="group___f_a_p_l.html#ga89b9f918d53dee5e6c80060667b8d32f" title="get the onion info from the file access property list">H5Pget_fapl_onion</a> </td><td>Modifies/queries the file driver properties of the onion driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gaad28d8c24f236590193215c5ae7a8f18" title="Modifies the specified File Access Property List to use the H5FD_ROS3 driver.">H5Pset_fapl_ros3</a>/<a class="el" href="group___f_a_p_l.html#ga13e273711e160cbd58e60c701b4f50e6" title="Queries a File Access Property List for H5FD_ROS3 file driver properties.">H5Pget_fapl_ros3</a> </td><td>Modifies/queries the file driver properties of the ros3 driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#gaf581bceca36ad4eef3cd45b16eabbb20" title="Modifies the file access property list to use the H5FD_SEC2 driver.">H5Pset_fapl_sec2</a> </td><td>Sets driver for unbuffered permanent files or retrieves information regarding driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga502f1ad38f5143cf281df8282fef26ed" title="Emulates the old split file driver.">H5Pset_fapl_split</a> </td><td>Sets driver for split files, a limited case of multi driver with one metadata file and one raw data file. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga49f386ea235bb48128e54c962c499f07" title="Sets the file access property list to use the splitter driver.">H5Pset_fapl_splitter</a>/<a class="el" href="group___f_a_p_l.html#gaf6ac1c131acee33dfb878593dfefb4ac" title="Gets splitter driver properties from the the file access property list.">H5Pget_fapl_splitter</a> </td><td>Modifies/queries the file driver properties of the splitter driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga77f0643117835e7f7992d573761b5052" title="Sets the standard I/O driver.">H5Pset_fapl_stdio</a> </td><td>Sets driver for buffered permanent files. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga65dbddbba216fdd0bdf99b4feaa74db2" title="Modifies the specified File Access Property List to use the H5FD_SUBFILING driver.">H5Pset_fapl_subfiling</a>/<a class="el" href="group___f_a_p_l.html#ga2af70900a3ea50a83d65f8285730ef45" title="Queries a File Access Property List for H5FD_SUBFILING file driver properties.">H5Pget_fapl_subfiling</a> </td><td>Modifies/queries the file driver properties of the subfiling driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830" title="Sets the Windows I/O driver.">H5Pset_fapl_windows</a> </td><td>Sets the Windows I/O driver. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga507341f31848c57008a3225bff3fe128" title="Specifies type of data to be accessed via the MULTI driver, enabling more direct access.">H5Pset_multi_type</a> </td><td>Specifies type of data to be accessed via the MULTI driver enabling more direct access. </td></tr>
<tr>
<td><a class="el" href="group___f_a_p_l.html#ga251515e9fee4641037b4866a4f7c49fe" title="Retrieves type of data property for MULTI driver.">H5Pget_multi_type</a> </td><td>Retrieves type of data property for MULTI driver. </td></tr>
</table>
</div><div> </div><h2><a class="anchor" id="subsec_file_create"></a>
Creating or Opening an HDF5 File</h2>
<p>This section describes in more detail how to create and how to open files.</p>
<p>New HDF5 files are created and opened with <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a>; existing files are opened with <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a>. Both functions return an object identifier which must eventually be released by calling <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>.</p>
<p>To create a new file, call <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a>: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a> (<span class="keyword">const</span> <span class="keywordtype">char</span> *name, <span class="keywordtype">unsigned</span> flags, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fcpl_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id)</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><!-- fragment --><p><a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> creates a new file named name in the current directory. The file is opened with read and write access; if the <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> flag is set, any pre-existing file of the same name in the same directory is truncated. If <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> is not set or <a class="el" href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</a> is set and if a file of the same name exists, <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> will fail.</p>
<p>The new file is created with the properties specified in the property lists fcpl_id and fapl_id. fcpl is short for file creation property list. fapl is short for file access property list. Specifying <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> for either the creation or access property list will use the library's default creation or access properties.</p>
<p>If <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> successfully creates the file, it returns a file identifier for the new file. This identifier will be used by the application any time an object identifier, an OID, for the file is required. Once the application has finished working with a file, the identifier should be released and the file closed with <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>.</p>
<p>To open an existing file, call <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a>: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a> (<span class="keyword">const</span> <span class="keywordtype">char</span> *name, <span class="keywordtype">unsigned</span> flags, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id)</div>
</div><!-- fragment --><p><a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> opens an existing file with read-write access if <a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a> is set and read-only access if <a class="el" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a> is set.</p>
<p>fapl_id is the file access property list identifier. Alternatively, <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> indicates that the application relies on the default I/O access parameters. Creating and changing access property lists is documented further below.</p>
<p>A file can be opened more than once via multiple <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> calls. Each such call returns a unique file identifier and the file can be accessed through any of these file identifiers as long as they remain valid. Each of these file identifiers must be released by calling <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> when it is no longer needed.</p>
<p>For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="#subsubsec_file_property_lists_access">File Access Properties</a>. For more information, </dd>
<dd>
<a class="el" href="#subsec_file_property_lists">File Property Lists</a>.</dd></dl>
<h2><a class="anchor" id="subsec_file_closes"></a>
Closing an HDF5 File</h2>
<p><a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> both closes a file and releases the file identifier returned by <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> or <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a>. <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> must be called when an application is done working with a file; while the HDF5 Library makes every effort to maintain file integrity, failure to call <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> may result in the file being abandoned in an incomplete or corrupted state.</p>
<p>To close a file, call <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>: </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_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id)</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><!-- fragment --><p> This function releases resources associated with an open file. After closing a file, the file identifier, file_id, cannot be used again as it will be undefined.</p>
<p><a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> fulfills three purposes: to ensure that the file is left in an uncorrupted state, to ensure that all data has been written to the file, and to release resources. Use <a class="el" href="group___h5_f.html#gae686870f0a276c4d06bbc667b2c24124" title="Flushes all buffers associated with a file to storage.">H5Fflush</a> if you wish to ensure that all data has been written to the file but it is premature to close it.</p>
<p>Note regarding serial mode behavior: When <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> is called in serial mode, it closes the file and terminates new access to it, but it does not terminate access to objects that remain individually open within the file. That is, if <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> is called for a file but one or more objects within the file remain open, those objects will remain accessible until they are individually closed. To illustrate, assume that a file, fileA, contains a dataset, data_setA, and that both are open when <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> is called for fileA. data_setA will remain open and accessible, including writable, until it is explicitly closed. The file will be automatically and finally closed once all objects within it have been closed.</p>
<p>Note regarding parallel mode behavior: Once <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> has been called in parallel mode, access is no longer available to any object within the file.</p>
<h2><a class="anchor" id="subsec_file_property_lists"></a>
File Property Lists</h2>
<p>Additional information regarding file structure and access are passed to <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> and <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> through property list objects. Property lists provide a portable and extensible method of modifying file properties via simple API functions. There are two kinds of file-related property lists: </p><ul>
<li>File creation property lists </li>
<li>File access property lists</li>
</ul>
<p>In the following sub-sections, we discuss only one file creation property, userblock size, in detail as a model for the user. Other file creation and file access properties are mentioned and defined briefly, but the model is not expanded for each; complete syntax, parameter, and usage information for every property list function is provided in the <a class="el" href="group___h5_p.html">Property Lists (H5P)</a> section of the HDF5 Reference Manual.</p>
<p>For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_h5_p__u_g.html#sec_plist">Properties and Property Lists in HDF5</a>.</dd></dl>
<h3><a class="anchor" id="subsubsec_file_property_lists_create"></a>
Creating a Property List</h3>
<p>If you do not wish to rely on the default file creation and access properties, you must first create a property list with <a class="el" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa" title="Creates a new property list as an instance of a property list class.">H5Pcreate</a>. </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> cls_id)</div>
</div><!-- fragment --><p> cls_id is the type of property list being created. In this case, the appropriate values are <a class="el" href="_h5_ppublic_8h.html#a206f334f1e6c973e1215a3148b45b977">H5P_FILE_CREATE</a> for a file creation property list and <a class="el" href="_h5_ppublic_8h.html#a60ec2d4334addfc0eda89614598ee38e">H5P_FILE_ACCESS</a> for a file access property list.</p>
<p>Thus, the following calls create a file creation property list and a file access property list with identifiers fcpl_id and fapl_id, respectively: </p><div class="fragment"><div class="line">fcpl_id = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a> (<a class="code hl_define" href="_h5_ppublic_8h.html#a206f334f1e6c973e1215a3148b45b977">H5P_FILE_CREATE</a>)</div>
<div class="line">fapl_id = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a> (<a class="code hl_define" href="_h5_ppublic_8h.html#a60ec2d4334addfc0eda89614598ee38e">H5P_FILE_ACCESS</a>)</div>
</div><!-- fragment --><p>Once the property lists have been created, the properties themselves can be modified via the functions described in the following sub-sections.</p>
<h3><a class="anchor" id="subsubsec_file_property_lists_props"></a>
File Creation Properties</h3>
<p>File creation property lists control the file metadata, which is maintained in the superblock of the file. These properties are used only when a file is first created.</p>
<h4>Userblock Size</h4>
<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___f_c_p_l.html#ga403bd982a2976c932237b186ed1cff4d">H5Pset_userblock</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> plist, <a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> size)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___f_c_p_l.html#ga75b312bb0c70419fc428d743a65bed86">H5Pget_userblock</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> plist, <a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> *size)</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___f_c_p_l_html_ga403bd982a2976c932237b186ed1cff4d"><div class="ttname"><a href="group___f_c_p_l.html#ga403bd982a2976c932237b186ed1cff4d">H5Pset_userblock</a></div><div class="ttdeci">herr_t H5Pset_userblock(hid_t plist_id, hsize_t size)</div><div class="ttdoc">Sets user block size.</div></div>
<div class="ttc" id="agroup___f_c_p_l_html_ga75b312bb0c70419fc428d743a65bed86"><div class="ttname"><a href="group___f_c_p_l.html#ga75b312bb0c70419fc428d743a65bed86">H5Pget_userblock</a></div><div class="ttdeci">herr_t H5Pget_userblock(hid_t plist_id, hsize_t *size)</div><div class="ttdoc">Retrieves the size of a user block.</div></div>
</div><!-- fragment --><p>The userblock is a fixed-length block of data located at the beginning of the file and is ignored by the HDF5 library. This block is specifically set aside for any data or information that developers determine to be useful to their applications but that will not be used by the HDF5 library. The size of the userblock is defined in bytes and may be set to any power of two with a minimum size of 512 bytes. In other words, userblocks might be 512, 1024, or 2048 bytes in size.</p>
<p>This property is set with <a class="el" href="group___f_c_p_l.html#ga403bd982a2976c932237b186ed1cff4d" title="Sets user block size.">H5Pset_userblock</a> and queried via <a class="el" href="group___f_c_p_l.html#ga75b312bb0c70419fc428d743a65bed86" title="Retrieves the size of a user block.">H5Pget_userblock</a>. For example, if an application needed a 4K userblock, then the following function call could be used: </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___f_c_p_l.html#ga403bd982a2976c932237b186ed1cff4d">H5Pset_userblock</a>(fcpl_id, 4096)</div>
</div><!-- fragment --><p>The property list could later be queried with: </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___f_c_p_l.html#ga75b312bb0c70419fc428d743a65bed86">H5Pget_userblock</a>(fcpl_id, size)</div>
</div><!-- fragment --><p> and the value 4096 would be returned in the parameter size.</p>
<p>Other properties, described below, are set and queried in exactly the same manner. Syntax and usage are detailed in the <a class="el" href="group___h5_p.html">Property Lists (H5P)</a> section of the HDF5 Reference Manual.</p>
<h4>Offset and Length Sizes</h4>
<p>This property specifies the number of bytes used to store the offset and length of objects in the HDF5 file. Values of 2, 4, and 8 bytes are currently supported to accommodate 16-bit, 32-bit, and 64-bit file address spaces.</p>
<p>These properties are set and queried via <a class="el" href="group___f_c_p_l.html#gae5eb3ba16f063d151d1b56d33e0710a9" title="Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.">H5Pset_sizes</a> and <a class="el" href="group___f_c_p_l.html#ga8da25b0367cf226c2888141661fd7a2d" title="Retrieves the size of the offsets and lengths used in an HDF5 file.">H5Pget_sizes</a>.</p>
<h4>Symbol Table Parameters</h4>
<p>The size of symbol table B-trees can be controlled by setting the 1/2-rank and 1/2-node size parameters of the B-tree.</p>
<p>These properties are set and queried via <a class="el" href="group___f_c_p_l.html#ga444ca905f084f9f96b7fe60d2a8c8176">H5Pset_sym_k</a> and <a class="el" href="group___f_c_p_l.html#ga1d4ee26c030ced6d7a314543578c88b1" title="Retrieves the size of the symbol table B-tree 1/2 rank and the symbol table leaf node 1/2 size.">H5Pget_sym_k</a></p>
<h4>Indexed Storage Parameters</h4>
<p>The size of indexed storage B-trees can be controlled by setting the 1/2-rank and 1/2-node size parameters of the B-tree.</p>
<p>These properties are set and queried via <a class="el" href="group___f_c_p_l.html#ga84a72f59d17841c37ab34674bf22a10c" title="Sets the size of the parameter used to control the B-trees for indexing chunked datasets.">H5Pset_istore_k</a> and <a class="el" href="group___f_c_p_l.html#ga2179b032be5d2efbca63d8f82a292ec1" title="Queries the 1/2 rank of an indexed storage B-tree.">H5Pget_istore_k</a>.</p>
<h4>Version Information</h4>
<p>Various objects in an HDF5 file may over time appear in different versions. The HDF5 Library keeps track of the version of each object in the file.</p>
<p>Version information is retrieved via <a class="el" href="group___f_c_p_l.html#ga99c0afbb68e8e775ae70cac44404a534" title="Retrieves the version information of various objects for a file creation property list(deprecated)">H5Pget_version</a>.</p>
<h3><a class="anchor" id="subsubsec_file_property_lists_access"></a>
File Access Properties</h3>
<p>This section discusses file access properties that are not related to the low-level file drivers. File drivers are discussed separately later in this chapter. For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="#subsec_file_alternate_drivers">Alternate File Storage Layouts and Low-level File Drivers</a>.</dd></dl>
<p>File access property lists control various aspects of file I/O and structure.</p>
<h4>Data Alignment</h4>
<p>Sometimes file access is faster if certain data elements are aligned in a specific manner. This can be controlled by setting alignment properties via the <a class="el" href="group___f_a_p_l.html#gab99d5af749aeb3896fd9e3ceb273677a" title="Sets alignment properties of a file access property list.">H5Pset_alignment</a> function. There are two values involved: </p><ul>
<li>A threshold value </li>
<li>An alignment interval</li>
</ul>
<p>Any allocation request at least as large as the threshold will be aligned on an address that is a multiple of the alignment interval.</p>
<h4>Metadata Block Allocation Size</h4>
<p>Metadata typically exists as very small chunks of data; storing metadata elements in a file without blocking them can result in hundreds or thousands of very small data elements in the file. This can result in a highly fragmented file and seriously impede I/O. By blocking metadata elements, these small elements can be grouped in larger sets, thus alleviating both problems.</p>
<p><a class="el" href="group___f_a_p_l.html#ga8822e3dedc8e1414f20871a87d533cb1" title="Sets the minimum metadata block size.">H5Pset_meta_block_size</a> sets the minimum size in bytes of metadata block allocations. <a class="el" href="group___f_a_p_l.html#gac17861181246af0209c0da5209305461" title="Returns the current metadata block size setting.">H5Pget_meta_block_size</a> retrieves the current minimum metadata block allocation size.</p>
<h4>Metadata Cache</h4>
<p>Metadata and raw data I/O speed are often governed by the size and frequency of disk reads and writes. In many cases, the speed can be substantially improved by the use of an appropriate cache.</p>
<p><a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache</a> sets the minimum cache size for both metadata and raw data and a preemption value for raw data chunks. <a class="el" href="group___f_a_p_l.html#ga9481a0b08d729ec68897d57db1827861" title="Queries the raw data chunk cache parameters.">H5Pget_cache</a> retrieves the current values.</p>
<h4>Data Sieve Buffer Size</h4>
<p>Data sieve buffering is used by certain file drivers to speed data I/O and is most commonly when working with dataset hyperslabs. For example, using a buffer large enough to hold several pieces of a dataset as it is read in for hyperslab selections will boost performance noticeably.</p>
<p><a class="el" href="group___f_a_p_l.html#ga24fd737955839194bf5605d5f47928ee" title="Sets the maximum size of the data sieve buffer.">H5Pset_sieve_buf_size</a> sets the maximum size in bytes of the data sieve buffer. <a class="el" href="group___f_a_p_l.html#gac2321d0c34bb2b3cf33cd7bf02ca8e66" title="Returns maximum data sieve buffer size.">H5Pget_sieve_buf_size</a> retrieves the current maximum size of the data sieve buffer.</p>
<h4>Garbage Collection References</h4>
<p>Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on (1) and the user passes in an uninitialized value in a reference structure, the heap might become corrupted. When garbage collection is off (0), however, and the user reuses a reference, the previous heap block will be orphaned and not returned to the free heap space. When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.</p>
<p><a class="el" href="group___f_a_p_l.html#ga61f01a12d5392ccf1321168f3c28f36f" title="Sets garbage collecting references flag.">H5Pset_gc_references</a> sets the garbage collecting references flag.</p>
<h2><a class="anchor" id="subsec_file_alternate_drivers"></a>
Alternate File Storage Layouts and Low-level File Drivers</h2>
<p>The concept of an HDF5 file is actually rather abstract: the address space for what is normally thought of as an HDF5 file might correspond to any of the following: </p><ul>
<li>Single file on standard file system </li>
<li>Multiple files on standard file system </li>
<li>Multiple files on parallel file system </li>
<li>Block of memory within application's memory space </li>
<li>More abstract situations such as virtual files</li>
</ul>
<p>This HDF5 address space is generally referred to as an HDF5 file regardless of its organization at the storage level.</p>
<p>HDF5 employs an extremely flexible mechanism called the virtual file layer, or VFL, for file I/O. A full understanding of the VFL is only necessary if you plan to write your own drivers </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_v_f_l.html">HDF5 Virtual File Layer</a> in the HDF5 Technical Notes.</dd></dl>
<p>For our purposes here, it is sufficient to know that the low-level drivers used for file I/O reside in the VFL, as illustrated in the following figure. Note that H5FD_STREAM is not available with 1.8.x and later versions of the library.</p>
<table class="doxtable">
<tr>
<td><div class="image">
<img src="VFL_Drivers.gif" alt=""/>
<div class="caption">
I/O path from application to VFL and low-level drivers to storage</div></div>
</td></tr>
</table>
<p>As mentioned above, HDF5 applications access HDF5 files through various low-level file drivers. The default driver for that layout is the POSIX driver (also known as the SEC2 driver), <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>. Alternative layouts and drivers are designed to suit the needs of a variety of systems, environments, and applications. The drivers are listed in the table below.</p>
<div></div><div> <a class="anchor" id="table_file_drivers"></a>
<table class="doxtable">
<caption>Supported file drivers</caption>
<tr>
<th>Driver Name </th><th>Driver Identifier </th><th>Description </th><th>Related API </th></tr>
<tr>
<td>POSIX </td><td><a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a> </td><td>This driver uses POSIX file-system functions like read and write to perform I/O to a single, permanent file on local disk with no system buffering. This driver is POSIX-compliant and is the default file driver for all systems. </td><td><a class="el" href="group___f_a_p_l.html#gaf581bceca36ad4eef3cd45b16eabbb20" title="Modifies the file access property list to use the H5FD_SEC2 driver.">H5Pset_fapl_sec2</a> </td></tr>
<tr>
<td>Memory </td><td><a class="el" href="_h5_f_dcore_8h.html#ae449696f6b86abcd1120beab21fff76a">H5FD_CORE</a> </td><td>With this driver, an application can work with a file in memory for faster reads and writes. File contents are kept in memory until the file is closed. At closing, the memory version of the file can be written back to disk or abandoned. </td><td><a class="el" href="group___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849" title="Modifies the file access property list to use the H5FD_CORE driver.">H5Pset_fapl_core</a> </td></tr>
<tr>
<td>Log </td><td><a class="el" href="_h5_f_dlog_8h.html#a027aaf28f5104c77c4f51ecd29a5f7f4">H5FD_LOG</a> </td><td>This is the <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a> driver with logging capabilities. </td><td><a class="el" href="group___f_a_p_l.html#ga4e03be2fe83ed02b32266a6c81427beb" title="Sets up the logging virtual file driver (H5FD_LOG) for use.">H5Pset_fapl_log</a> </td></tr>
<tr>
<td>Family </td><td><a class="el" href="_h5_f_dfamily_8h.html#adbf24f060712550a2a9649589a6060c6">H5FD_FAMILY</a> </td><td>With this driver, the HDF5 file's address space is partitioned into pieces and sent to separate storage files using an underlying driver of the user's choice. This driver is for systems that do not support files larger than 2 gigabytes. </td><td><a class="el" href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53" title="Sets the file access property list to use the family driver.">H5Pset_fapl_family</a> </td></tr>
<tr>
<td>Multi </td><td><a class="el" href="_h5_f_dmulti_8h.html#a754e05ae5e0f2d86f64002b338c0fd5c">H5FD_MULTI</a> </td><td>With this driver, data can be stored in multiple files according to the type of the data. I/O might work better if data is stored in separate files based on the type of data. The Split driver is a special case of this driver. </td><td><a class="el" href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58" title="Sets up use of the multi-file driver.">H5Pset_fapl_multi</a> / <a class="el" href="group___f_a_p_l.html#ga502f1ad38f5143cf281df8282fef26ed" title="Emulates the old split file driver.">H5Pset_fapl_split</a> </td></tr>
<tr>
<td>STDIO </td><td><a class="el" href="_h5_f_dstdio_8h.html#a030a03b96a9f6e46035ce64e25389085">H5FD_STDIO</a> </td><td>This driver uses functions from the standard C stdio.h to perform I/O to a single, permanent file on local disk with additional system buffering. </td><td><a class="el" href="group___f_a_p_l.html#ga77f0643117835e7f7992d573761b5052" title="Sets the standard I/O driver.">H5Pset_fapl_stdio</a> </td></tr>
<tr>
<td>Split </td><td><a class="el" href="_h5_f_dsplitter_8h.html#ac6c45c6a8e1cb7f5b4400d95bf651eae">H5FD_SPLITTER</a> </td><td>This file driver splits a file into two parts. One part stores metadata, and the other part stores raw data. This splitting a file into two parts is a limited case of the Multi driver. </td><td><a class="el" href="group___f_a_p_l.html#ga49f386ea235bb48128e54c962c499f07" title="Sets the file access property list to use the splitter driver.">H5Pset_fapl_splitter</a> </td></tr>
<tr>
<td>Parallel </td><td><a class="el" href="_h5_f_dmpio_8h.html#a7a231bc1d78744088a4e1d297284cabf">H5FD_MPIO</a> </td><td>This is the standard HDF5 file driver for parallel file systems. This driver uses the MPI standard for both communication and file I/O. </td><td><a class="el" href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff" title="Stores MPI IO communicator information to the file access property list.">H5Pset_fapl_mpio</a> </td></tr>
<tr>
<td>Direct </td><td><a class="el" href="_h5_f_ddirect_8h.html#a99213f218f9ab0c51f9c679228a1e436">H5FD_DIRECT</a> </td><td>This is the <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a> driver except data is written to or read from the file synchronously without being cached by the system. </td><td><a class="el" href="group___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7" title="Sets up use of the direct I/O driver.">H5Pset_fapl_direct</a> </td></tr>
<tr>
<td>Mirror </td><td><a class="el" href="_h5_f_dmirror_8h.html#a05b78c6f3d122b4112632080474b3412">H5FD_MIRROR</a> </td><td>Serial I/O to file using Unix “stdio” functions. </td><td><a class="el" href="group___f_a_p_l.html#ga8491676811ccc7ba582e30fb63da6563" title="Modifies the file access property list to use the H5FD_MIRROR driver.">H5Pset_fapl_mirror</a> </td></tr>
<tr>
<td>HDFS </td><td><a class="el" href="_h5_f_dhdfs_8h.html#ac3868cc2fa0e9aec4bcb52830906d584">H5FD_HDFS</a> </td><td>Read-Only access to Hadoop Distributed File System (HDFS). </td><td><a class="el" href="group___f_a_p_l.html#ga970d077c8e712a4692f43fa4f38dde14" title="Modifies the file access property list to use the H5FD_HDFS driver.">H5Pset_fapl_hdfs</a> </td></tr>
<tr>
<td>ros3 </td><td><a class="el" href="_h5_f_dros3_8h.html#ace004a4771dcfd40a4c0adecc1974570">H5FD_ROS3</a> </td><td>Read-Only access to Amazon's S3 service. </td><td><a class="el" href="group___f_a_p_l.html#gaad28d8c24f236590193215c5ae7a8f18" title="Modifies the specified File Access Property List to use the H5FD_ROS3 driver.">H5Pset_fapl_ros3</a> </td></tr>
<tr>
<td>Subfiling </td><td><a class="el" href="_h5_f_dsubfiling_8h.html#a070ba7b51cfe718ba4da75b308066a9d">H5FD_SUBFILING</a> </td><td>Derived from other "stacked" VFDs such as the splitter, mirror, and family VFDs. </td><td><a class="el" href="group___f_a_p_l.html#ga65dbddbba216fdd0bdf99b4feaa74db2" title="Modifies the specified File Access Property List to use the H5FD_SUBFILING driver.">H5Pset_fapl_subfiling</a> </td></tr>
<tr>
<td>IOC </td><td><a class="el" href="_h5_f_dioc_8h.html#a9d6649a67050fb1101cca3596421b986">H5FD_IOC</a> </td><td>Relays VFD calls to one VFD, and write calls to another VFD. Maintains two files. </td><td><a class="el" href="group___f_a_p_l.html#ga714340ec9cbb65cb0a819e1d775825f0" title="Modifies the specified File Access Property List to use the H5FD_IOC driver.">H5Pset_fapl_ioc</a> </td></tr>
<tr>
<td>Onion </td><td><a class="el" href="_h5_f_donion_8h.html#a1d6673897b4ebd1bad9846b5695ba346">H5FD_ONION</a> </td><td>Provide in-file provenance and revision/version control. </td><td><a class="el" href="group___f_a_p_l.html#ga4d053c7682e54287e550113972b7dda6" title="set the onion info for the file access property list">H5Pset_fapl_onion</a> </td></tr>
<tr>
<td>Windows </td><td><a class="el" href="_h5_f_dwindows_8h.html#ab5173993ddefd103bfb3d37c2837a9a4">H5FD_WINDOWS</a> </td><td>This driver was modified in HDF5-1.8.8 to be a wrapper of the POSIX driver, <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>. This change should not affect user applications. </td><td><a class="el" href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830" title="Sets the Windows I/O driver.">H5Pset_fapl_windows</a> </td></tr>
<tr>
<td>Parallel POSIX </td><td>H5FD_MPIPOSIX </td><td>This driver is no longer available </td><td></td></tr>
<tr>
<td>Stream </td><td>H5FD_STREAM </td><td>This driver is no longer available. </td><td></td></tr>
</table>
</div><div> </div><p>For more information, see the HDF5 Reference Manual entries for the function calls shown in the column on the right in the table above.</p>
<p>Note that the low-level file drivers manage alternative file storage layouts. Dataset storage layouts (chunking, compression, and external dataset storage) are managed independently of file storage layouts.</p>
<p>If an application requires a special-purpose low-level driver, the VFL provides a public API for creating one. For more information on how to create a driver, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_v_f_l.html">HDF5 Virtual File Layer</a> in the HDF5 Technical Notes.</dd></dl>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_id"></a>
Identifying the Previously‐used File Driver</h3>
<p>When creating a new HDF5 file, no history exists, so the file driver must be specified if it is to be other than the default.</p>
<p>When opening existing files, however, the application may need to determine which low-level driver was used to create the file. The function <a class="el" href="group___f_a_p_l.html#ga43a733fe9723dd15f5ad7abda909a1b8" title="Returns low-lever driver identifier.">H5Pget_driver</a> is used for this purpose. See the example below.</p>
<p><em>Identifying a driver</em> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_function" href="group___f_a_p_l.html#ga43a733fe9723dd15f5ad7abda909a1b8">H5Pget_driver</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga43a733fe9723dd15f5ad7abda909a1b8"><div class="ttname"><a href="group___f_a_p_l.html#ga43a733fe9723dd15f5ad7abda909a1b8">H5Pget_driver</a></div><div class="ttdeci">hid_t H5Pget_driver(hid_t plist_id)</div><div class="ttdoc">Returns low-lever driver identifier.</div></div>
</div><!-- fragment --><p><a class="el" href="group___f_a_p_l.html#ga43a733fe9723dd15f5ad7abda909a1b8" title="Returns low-lever driver identifier.">H5Pget_driver</a> returns a constant identifying the low-level driver for the access property list fapl_id. For example, if the file was created with the POSIX (aka SEC2) driver, <a class="el" href="group___f_a_p_l.html#ga43a733fe9723dd15f5ad7abda909a1b8" title="Returns low-lever driver identifier.">H5Pget_driver</a> returns <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>.</p>
<p>If the application opens an HDF5 file without both determining the driver used to create the file and setting up the use of that driver, the HDF5 Library will examine the superblock and the driver definition block to identify the driver. See the <a href="https://hdfgroup.github.io/hdf5/develop/_s_p_e_c.html">HDF5 File Format Specification</a> for detailed descriptions of the superblock and the driver definition block.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_sec2"></a>
The POSIX (aka SEC2) Driver</h3>
<p>The POSIX driver, <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>, uses functions from section 2 of the POSIX manual to access unbuffered files stored on a local file system. This driver is also known as the SEC2 driver. The HDF5 Library buffers metadata regardless of the low-level driver, but using this driver prevents data from being buffered again by the lowest layers of the library.</p>
<p>The function <a class="el" href="group___f_a_p_l.html#gaf581bceca36ad4eef3cd45b16eabbb20" title="Modifies the file access property list to use the H5FD_SEC2 driver.">H5Pset_fapl_sec2</a> sets the file access properties to use the POSIX driver. See the example below.</p>
<p><em>Using the POSIX, aka SEC2, driver</em> </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___f_a_p_l.html#gaf581bceca36ad4eef3cd45b16eabbb20">H5Pset_fapl_sec2</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id)</div>
<div class="ttc" id="agroup___f_a_p_l_html_gaf581bceca36ad4eef3cd45b16eabbb20"><div class="ttname"><a href="group___f_a_p_l.html#gaf581bceca36ad4eef3cd45b16eabbb20">H5Pset_fapl_sec2</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_sec2(hid_t fapl_id)</div><div class="ttdoc">Modifies the file access property list to use the H5FD_SEC2 driver.</div></div>
</div><!-- fragment --><p>Any previously-defined driver properties are erased from the property list.</p>
<p>Additional parameters may be added to this function in the future. Since there are no additional variable settings associated with the POSIX driver, there is no H5Pget_fapl_sec2 function.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_direct"></a>
The Direct Driver</h3>
<p>The Direct driver, <a class="el" href="_h5_f_ddirect_8h.html#a99213f218f9ab0c51f9c679228a1e436">H5FD_DIRECT</a>, functions like the POSIX driver except that data is written to or read from the file synchronously without being cached by the system.</p>
<p>The functions <a class="el" href="group___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7" title="Sets up use of the direct I/O driver.">H5Pset_fapl_direct</a> and <a class="el" href="group___f_a_p_l.html#ga038e5f3952e49b6945039fc2b010ab16" title="Retrieves direct I/O driver settings.">H5Pget_fapl_direct</a> are used to manage file access properties. See the example below.</p>
<p><em>Using the Direct driver</em> </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___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7">H5Pset_fapl_direct</a>(<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, <span class="keywordtype">size_t</span> alignment, <span class="keywordtype">size_t</span> block_size, <span class="keywordtype">size_t</span> cbuf_size)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___f_a_p_l.html#ga038e5f3952e49b6945039fc2b010ab16">H5Pget_fapl_direct</a>(<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, <span class="keywordtype">size_t</span> *alignment, <span class="keywordtype">size_t</span> *block_size, <span class="keywordtype">size_t</span> *cbuf_size)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga038e5f3952e49b6945039fc2b010ab16"><div class="ttname"><a href="group___f_a_p_l.html#ga038e5f3952e49b6945039fc2b010ab16">H5Pget_fapl_direct</a></div><div class="ttdeci">H5_DLL herr_t H5Pget_fapl_direct(hid_t fapl_id, size_t *boundary, size_t *block_size, size_t *cbuf_size)</div><div class="ttdoc">Retrieves direct I/O driver settings.</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_ga2839252e149484ef30fb214ae7b44ac7"><div class="ttname"><a href="group___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7">H5Pset_fapl_direct</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_direct(hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size)</div><div class="ttdoc">Sets up use of the direct I/O driver.</div></div>
</div><!-- fragment --><p><a class="el" href="group___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7" title="Sets up use of the direct I/O driver.">H5Pset_fapl_direct</a> sets the file access properties to use the Direct driver; any previously defined driver properties are erased from the property list. <a class="el" href="group___f_a_p_l.html#ga038e5f3952e49b6945039fc2b010ab16" title="Retrieves direct I/O driver settings.">H5Pget_fapl_direct</a> retrieves the file access properties used with the Direct driver. fapl_id is the file access property list identifier. alignment is the memory alignment boundary. block_size is the file system block size. cbuf_size is the copy buffer size.</p>
<p>Additional parameters may be added to this function in the future.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_log"></a>
The Log Driver</h3>
<p>The Log driver, <a class="el" href="_h5_f_dlog_8h.html#a027aaf28f5104c77c4f51ecd29a5f7f4">H5FD_LOG</a>, is designed for situations where it is necessary to log file access activity.</p>
<p>The function <a class="el" href="group___f_a_p_l.html#ga4e03be2fe83ed02b32266a6c81427beb" title="Sets up the logging virtual file driver (H5FD_LOG) for use.">H5Pset_fapl_log</a> is used to manage logging properties. See the example below.</p>
<p><em>Logging file access</em> </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___f_a_p_l.html#ga4e03be2fe83ed02b32266a6c81427beb">H5Pset_fapl_log</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, <span class="keyword">const</span> <span class="keywordtype">char</span> *logfile, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> flags, <span class="keywordtype">size_t</span> buf_size)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga4e03be2fe83ed02b32266a6c81427beb"><div class="ttname"><a href="group___f_a_p_l.html#ga4e03be2fe83ed02b32266a6c81427beb">H5Pset_fapl_log</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_log(hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size)</div><div class="ttdoc">Sets up the logging virtual file driver (H5FD_LOG) for use.</div></div>
</div><!-- fragment --><p><a class="el" href="group___f_a_p_l.html#ga4e03be2fe83ed02b32266a6c81427beb" title="Sets up the logging virtual file driver (H5FD_LOG) for use.">H5Pset_fapl_log</a> sets the file access property list to use the Log driver. File access characteristics are identical to access via the POSIX driver. Any previously defined driver properties are erased from the property list.</p>
<p>Log records are written to the file logfile.</p>
<p>The logging levels set with the verbosity parameter are shown in the table below.</p>
<table class="doxtable">
<caption>Logging levels</caption>
<tr>
<th>Level </th><th>Comments </th></tr>
<tr>
<td>0 </td><td>Performs no logging. </td></tr>
<tr>
<td>1 </td><td>Records where writes and reads occur in the file. </td></tr>
<tr>
<td>2 </td><td>Records where writes and reads occur in the file and what kind of data is written at each location. This includes raw data or any of several types of metadata (object headers, superblock, B-tree data, local headers, or global headers). </td></tr>
</table>
<p>There is no H5Pget_fapl_log function.</p>
<p>Additional parameters may be added to this function in the future.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_win"></a>
The Windows Driver</h3>
<p>The Windows driver, <a class="el" href="_h5_f_dwindows_8h.html#ab5173993ddefd103bfb3d37c2837a9a4">H5FD_WINDOWS</a>, was modified in HDF5-1.8.8 to be a wrapper of the POSIX driver, <a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>. In other words, if the Windows drivers is used, any file I/O will instead use the functionality of the POSIX driver. This change should be transparent to all user applications. The Windows driver used to be the default driver for Windows systems. The POSIX driver is now the default.</p>
<p>The function <a class="el" href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830" title="Sets the Windows I/O driver.">H5Pset_fapl_windows</a> sets the file access properties to use the Windows driver. See the example below.</p>
<p><em>Using the Windows driver</em> </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___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830">H5Pset_fapl_windows</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga0017f78e0f3de465621fde556f679830"><div class="ttname"><a href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830">H5Pset_fapl_windows</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_windows(hid_t fapl_id)</div><div class="ttdoc">Sets the Windows I/O driver.</div></div>
</div><!-- fragment --><p>Any previously-defined driver properties are erased from the property list.</p>
<p>Additional parameters may be added to this function in the future. Since there are no additional variable settings associated with the POSIX driver, there is no H5Pget_fapl_windows function.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_stdio"></a>
The STDIO Driver</h3>
<p>The STDIO driver, <a class="el" href="_h5_f_dstdio_8h.html#a030a03b96a9f6e46035ce64e25389085">H5FD_STDIO</a>, accesses permanent files in a local file system like the POSIX driver does. The STDIO driver also has an additional layer of buffering beneath the HDF5 Library.</p>
<p>The function <a class="el" href="group___f_a_p_l.html#ga77f0643117835e7f7992d573761b5052" title="Sets the standard I/O driver.">H5Pset_fapl_stdio</a> sets the file access properties to use the STDIO driver. See the example below.</p>
<p><em>Using the STDIO driver</em> </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___f_a_p_l.html#ga77f0643117835e7f7992d573761b5052">H5Pset_fapl_stdio</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id)</div>
</div><!-- fragment --><p>Any previously defined driver properties are erased from the property list.</p>
<p>Additional parameters may be added to this function in the future. Since there are no additional variable settings associated with the STDIO driver, there is no H5Pget_fapl_stdio function.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_mem"></a>
The Memory (aka Core) Driver</h3>
<p>There are several situations in which it is reasonable, sometimes even required, to maintain a file entirely in system memory. You might want to do so if, for example, either of the following conditions apply: </p><ul>
<li>
Performance requirements are so stringent that disk latency is a limiting factor </li>
<li>
You are working with small, temporary files that will not be retained and, thus, need not be written to storage media</li>
</ul>
<p>The Memory driver, <a class="el" href="_h5_f_dcore_8h.html#ae449696f6b86abcd1120beab21fff76a">H5FD_CORE</a>, provides a mechanism for creating and managing such in memory files. The functions <a class="el" href="group___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849" title="Modifies the file access property list to use the H5FD_CORE driver.">H5Pset_fapl_core</a> and <a class="el" href="group___f_a_p_l.html#gac347d401cbb28fecd78c5f15ddb4c9c1" title="Queries core file driver properties.">H5Pget_fapl_core</a> manage file access properties. See the example below.</p>
<p><em>Managing file access for in-memory files</em> </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___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849">H5Pset_fapl_core</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> access_properties, <span class="keywordtype">size_t</span> block_size, <span class="keywordtype">bool</span> backing_store)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___f_a_p_l.html#gac347d401cbb28fecd78c5f15ddb4c9c1">H5Pget_fapl_core</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> access_properties, <span class="keywordtype">size_t</span> *block_size), <span class="keywordtype">bool</span> *backing_store)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga6e6628f620a1c58c704129cf07282849"><div class="ttname"><a href="group___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849">H5Pset_fapl_core</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_core(hid_t fapl_id, size_t increment, hbool_t backing_store)</div><div class="ttdoc">Modifies the file access property list to use the H5FD_CORE driver.</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_gac347d401cbb28fecd78c5f15ddb4c9c1"><div class="ttname"><a href="group___f_a_p_l.html#gac347d401cbb28fecd78c5f15ddb4c9c1">H5Pget_fapl_core</a></div><div class="ttdeci">H5_DLL herr_t H5Pget_fapl_core(hid_t fapl_id, size_t *increment, hbool_t *backing_store)</div><div class="ttdoc">Queries core file driver properties.</div></div>
</div><!-- fragment --><p><a class="el" href="group___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849" title="Modifies the file access property list to use the H5FD_CORE driver.">H5Pset_fapl_core</a> sets the file access property list to use the Memory driver; any previously defined driver properties are erased from the property list.</p>
<p>Memory for the file will always be allocated in units of the specified block_size.</p>
<p>The backing_store Boolean flag is set when the in-memory file is created. backing_store indicates whether to write the file contents to disk when the file is closed. If backing_store is set to 1 (true), the file contents are flushed to a file with the same name as the in-memory file when the file is closed or access to the file is terminated in memory. If backing_store is set to 0 (false), the file is not saved.</p>
<p>The application is allowed to open an existing file with the <a class="el" href="_h5_f_dcore_8h.html#ae449696f6b86abcd1120beab21fff76a">H5FD_CORE</a> driver. While using <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> to open an existing file, if backing_store is set to 1 and the flag for <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> is set to <a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a>, changes to the file contents will be saved to the file when the file is closed. If backing_store is set to 0 and the flag for <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> is set to <a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a>, changes to the file contents will be lost when the file is closed. If the flag for <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> is set to <a class="el" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a>, no change to the file will be allowed either in memory or on file.</p>
<p>If the file access property list is set to use the Memory driver, <a class="el" href="group___f_a_p_l.html#gac347d401cbb28fecd78c5f15ddb4c9c1" title="Queries core file driver properties.">H5Pget_fapl_core</a> will return block_size and backing_store with the relevant file access property settings.</p>
<p>Note the following important points regarding in-memory files: </p><ul>
<li>
Local temporary files are created and accessed directly from memory without ever being written to disk </li>
<li>
Total file size must not exceed the available virtual memory </li>
<li>
Only one HDF5 file identifier can be opened for the file, the identifier returned by <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> or <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> </li>
<li>
The changes to the file will be discarded when access is terminated unless backing_store is set to 1</li>
</ul>
<p>Additional parameters may be added to these functions in the future.</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations">HDF5 File Image Operations</a> section for information on more advanced usage of the Memory file driver, and </dd>
<dd>
<a href="http://www.hdfgroup.org/HDF5/doc/Advanced/ModifiedRegionWrites/ModifiedRegionWrites.pdf">Modified Region Writes</a> section for information on how to set write operations so that only modified regions are written to storage.</dd></dl>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_family"></a>
The Family Driver</h3>
<p>HDF5 files can become quite large, and this can create problems on systems that do not support files larger than 2 gigabytes. The HDF5 file family mechanism is designed to solve the problems this creates by splitting the HDF5 file address space across several smaller files. This structure does not affect how metadata and raw data are stored: they are mixed in the address space just as they would be in a single, contiguous file.</p>
<p>HDF5 applications access a family of files via the Family driver, <a class="el" href="_h5_f_dfamily_8h.html#adbf24f060712550a2a9649589a6060c6">H5FD_FAMILY</a>. The functions <a class="el" href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53" title="Sets the file access property list to use the family driver.">H5Pset_fapl_family</a> and <a class="el" href="group___f_a_p_l.html#ga0bc1a003f26bf4b53e4487b6ca117389" title="Returns file access property list information.">H5Pget_fapl_family</a> are used to manage file family properties. See the example below.</p>
<p><em>Managing file family properties</em> </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___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53">H5Pset_fapl_family</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id,</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> memb_size, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> member_properties)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___f_a_p_l.html#ga0bc1a003f26bf4b53e4487b6ca117389">H5Pget_fapl_family</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id,</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> *memb_size, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> *member_properties)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga0bc1a003f26bf4b53e4487b6ca117389"><div class="ttname"><a href="group___f_a_p_l.html#ga0bc1a003f26bf4b53e4487b6ca117389">H5Pget_fapl_family</a></div><div class="ttdeci">H5_DLL herr_t H5Pget_fapl_family(hid_t fapl_id, hsize_t *memb_size, hid_t *memb_fapl_id)</div><div class="ttdoc">Returns file access property list information.</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_ga95d19da25f196ce1ace10af00f49ab53"><div class="ttname"><a href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53">H5Pset_fapl_family</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_family(hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id)</div><div class="ttdoc">Sets the file access property list to use the family driver.</div></div>
</div><!-- fragment --><p>Each member of the family is the same logical size though the size and disk storage reported by file system listing tools may be substantially smaller. Examples of file system listing tools are </p><div class="fragment"><div class="line">ls -l</div>
</div><!-- fragment --><p> on a Unix system or the detailed folder listing on an Apple or Microsoft Windows system. The name passed to <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> or <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> should include a printf(3c)-style integer format specifier which will be replaced with the family member number. The first family member is numbered zero (0).</p>
<p><a class="el" href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53" title="Sets the file access property list to use the family driver.">H5Pset_fapl_family</a> sets the access properties to use the Family driver; any previously defined driver properties are erased from the property list. member_properties will serve as the file access property list for each member of the file family. memb_size specifies the logical size, in bytes, of each family member. memb_size is used only when creating a new file or truncating an existing file; otherwise the member size is determined by the size of the first member of the family being opened. Note: If the size of the off_t type is four bytes, the maximum family member size is usually 2^31-1 because the byte at offset 2,147,483,647 is generally inaccessible.</p>
<p><a class="el" href="group___f_a_p_l.html#ga0bc1a003f26bf4b53e4487b6ca117389" title="Returns file access property list information.">H5Pget_fapl_family</a> is used to retrieve file family properties. If the file access property list is set to use the Family driver, member_properties will be returned with a pointer to a copy of the appropriate member access property list. If memb_size is non-null, it will contain the logical size, in bytes, of family members.</p>
<p>Additional parameters may be added to these functions in the future.</p>
<h4>Unix Tools and an HDF5 Utility</h4>
<p>It occasionally becomes necessary to repartition a file family. A command-line utility for this purpose, h5repart, is distributed with the HDF5 library.</p>
<div class="fragment"><div class="line">h5repart [-v] [-b block_size[suffix]] [-m member_size[suffix]] source destination</div>
</div><!-- fragment --><p>h5repart repartitions an HDF5 file by copying the source file or file family to the destination file or file family, preserving holes in the underlying UNIX files. Families are used for the source and/or destination if the name includes a printf-style integer format such as d. The -v switch prints input and output file names on the standard error stream for progress monitoring, -b sets the I/O block size (the default is 1KB), and -m sets the output member size if the destination is a family name (the default is 1GB). block_size and member_size may be suffixed with the letters g, m, or k for GB, MB, or KB respectively.</p>
<p>The h5repart utility is described on the Tools page of the HDF5 Reference Manual.</p>
<p>An existing HDF5 file can be split into a family of files by running the file through split(1) on a UNIX system and numbering the output files. However, the HDF5 Library is lazy about extending the size of family members, so a valid file cannot generally be created by concatenation of the family members.</p>
<p>Splitting the file and rejoining the segments by concatenation (split(1) and cat(1) on UNIX systems) does not generate files with holes; holes are preserved only through the use of h5repart.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_multi"></a>
The Multi Driver</h3>
<p>In some circumstances, it is useful to separate metadata from raw data and some types of metadata from other types of metadata. Situations that would benefit from use of the Multi driver include the following: </p><ul>
<li>
In networked situations where the small metadata files can be kept on local disks but larger raw data files must be stored on remote media </li>
<li>
In cases where the raw data is extremely large </li>
<li>
In situations requiring frequent access to metadata held in RAM while the raw data can be efficiently held on disk</li>
</ul>
<p>In either case, access to the metadata is substantially easier with the smaller, and possibly more localized, metadata files. This often results in improved application performance.</p>
<p>The Multi driver, <a class="el" href="_h5_f_dmulti_8h.html#a754e05ae5e0f2d86f64002b338c0fd5c">H5FD_MULTI</a>, provides a mechanism for segregating raw data and different types of metadata into multiple files. The functions <a class="el" href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58" title="Sets up use of the multi-file driver.">H5Pset_fapl_multi</a> and <a class="el" href="group___f_a_p_l.html#ga765b7880795a139f3b567743ac88c3c7" title="Returns information about the multi-file access property list.">H5Pget_fapl_multi</a> are used to manage access properties for these multiple files. See the example below.</p>
<p><em>Managing access properties for multiple files</em> </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___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58">H5Pset_fapl_multi</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, <span class="keyword">const</span> <a class="code hl_typedef" href="_h5_f_dpublic_8h.html#a02887a6f018be1a0ce7358522095578b">H5FD_mem_t</a> *memb_map, <span class="keyword">const</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> *memb_fapl,</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> * <span class="keyword">const</span> *memb_name, <span class="keyword">const</span> <a class="code hl_typedef" href="_h5public_8h.html#a8c86e866f40d7167cf9a1934c72b856f">haddr_t</a> *memb_addr,</div>
<div class="line"> <span class="keywordtype">bool</span> relax)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___f_a_p_l.html#ga765b7880795a139f3b567743ac88c3c7">H5Pget_fapl_multi</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, <span class="keyword">const</span> <a class="code hl_typedef" href="_h5_f_dpublic_8h.html#a02887a6f018be1a0ce7358522095578b">H5FD_mem_t</a> *memb_map, <span class="keyword">const</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> *memb_fapl,</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> **memb_name, <span class="keyword">const</span> <a class="code hl_typedef" href="_h5public_8h.html#a8c86e866f40d7167cf9a1934c72b856f">haddr_t</a> *memb_addr, <span class="keywordtype">bool</span> *relax)</div>
<div class="ttc" id="a_h5_f_dpublic_8h_html_a02887a6f018be1a0ce7358522095578b"><div class="ttname"><a href="_h5_f_dpublic_8h.html#a02887a6f018be1a0ce7358522095578b">H5FD_mem_t</a></div><div class="ttdeci">enum H5F_mem_t H5FD_mem_t</div><div class="ttdef"><b>Definition</b> H5FDpublic.h:260</div></div>
<div class="ttc" id="a_h5public_8h_html_a8c86e866f40d7167cf9a1934c72b856f"><div class="ttname"><a href="_h5public_8h.html#a8c86e866f40d7167cf9a1934c72b856f">haddr_t</a></div><div class="ttdeci">uint64_t haddr_t</div><div class="ttdef"><b>Definition</b> H5public.h:325</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_ga296bd22cc1e462351f8f0a00a46baf58"><div class="ttname"><a href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58">H5Pset_fapl_multi</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax)</div><div class="ttdoc">Sets up use of the multi-file driver.</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_ga765b7880795a139f3b567743ac88c3c7"><div class="ttname"><a href="group___f_a_p_l.html#ga765b7880795a139f3b567743ac88c3c7">H5Pget_fapl_multi</a></div><div class="ttdeci">H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map, hid_t *memb_fapl, char **memb_name, haddr_t *memb_addr, hbool_t *relax)</div><div class="ttdoc">Returns information about the multi-file access property list.</div></div>
</div><!-- fragment --><p><a class="el" href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58" title="Sets up use of the multi-file driver.">H5Pset_fapl_multi</a> sets the file access properties to use the Multi driver; any previously defined driver properties are erased from the property list. With the Multi driver invoked, the application will provide a base name to <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> or <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a>. The files will be named by that base name as modified by the rule indicated in memb_name. File access will be governed by the file access property list memb_properties.</p>
<p>See <a class="el" href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58" title="Sets up use of the multi-file driver.">H5Pset_fapl_multi</a> and <a class="el" href="group___f_a_p_l.html#ga765b7880795a139f3b567743ac88c3c7" title="Returns information about the multi-file access property list.">H5Pget_fapl_multi</a> in the HDF5 Reference Manual for descriptions of these functions and their usage.</p>
<p>Additional parameters may be added to these functions in the future.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_split"></a>
The Split Driver</h3>
<p>The Split driver is a limited case of the Multi driver where only two files are created. One file holds metadata, and the other file holds raw data. The function <a class="el" href="group___f_a_p_l.html#ga502f1ad38f5143cf281df8282fef26ed" title="Emulates the old split file driver.">H5Pset_fapl_split</a> is used to manage Split file access properties. See the example below.</p>
<p><em>Managing access properties for split files</em> </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___f_a_p_l.html#ga502f1ad38f5143cf281df8282fef26ed">H5Pset_fapl_split</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> access_properties, <span class="keyword">const</span> <span class="keywordtype">char</span> *meta_extension,</div>
<div class="line"> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> meta_properties,<span class="keyword">const</span> <span class="keywordtype">char</span> *raw_extension, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> raw_properties)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga502f1ad38f5143cf281df8282fef26ed"><div class="ttname"><a href="group___f_a_p_l.html#ga502f1ad38f5143cf281df8282fef26ed">H5Pset_fapl_split</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_split(hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id)</div><div class="ttdoc">Emulates the old split file driver.</div></div>
</div><!-- fragment --><p><a class="el" href="group___f_a_p_l.html#ga502f1ad38f5143cf281df8282fef26ed" title="Emulates the old split file driver.">H5Pset_fapl_split</a> sets the file access properties to use the Split driver; any previously defined driver properties are erased from the property list.</p>
<p>With the Split driver invoked, the application will provide a base file name such as file_name to <a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> or <a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a>. The metadata and raw data files in storage will then be named file_name.meta_extension and file_name.raw_extension, respectively. For example, if meta_extension is defined as .meta and raw_extension is defined as .raw, the final filenames will be file_name.meta and file_name.raw.</p>
<p>Each file can have its own file access property list. This allows the creative use of other lowlevel file drivers. For instance, the metadata file can be held in RAM and accessed via the Memory driver while the raw data file is stored on disk and accessed via the POSIX driver. Metadata file access will be governed by the file access property list in meta_properties. Raw data file access will be governed by the file access property list in raw_properties.</p>
<p>Additional parameters may be added to these functions in the future. Since there are no additional variable settings associated with the Split driver, there is no H5Pget_fapl_split function.</p>
<h3><a class="anchor" id="subsubsec_file_alternate_drivers_par"></a>
The Parallel Driver</h3>
<p>Parallel environments require a parallel low-level driver. HDF5's default driver for parallel systems is called the Parallel driver, <a class="el" href="_h5_f_dmpio_8h.html#a7a231bc1d78744088a4e1d297284cabf">H5FD_MPIO</a>. This driver uses the MPI standard for both communication and file I/O.</p>
<p>The functions <a class="el" href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff" title="Stores MPI IO communicator information to the file access property list.">H5Pset_fapl_mpio</a> and <a class="el" href="group___f_a_p_l.html#ga5d9e4b9f27791ccf19484a898f3fd6fa" title="Returns MPI IO communicator information.">H5Pget_fapl_mpio</a> are used to manage file access properties for the <a class="el" href="_h5_f_dmpio_8h.html#a7a231bc1d78744088a4e1d297284cabf">H5FD_MPIO</a> driver. See the example below.</p>
<p><em>Managing parallel file access properties</em> </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___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff">H5Pset_fapl_mpio</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, MPI_Comm comm, MPI_info info)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___f_a_p_l.html#ga5d9e4b9f27791ccf19484a898f3fd6fa">H5Pget_fapl_mpio</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> fapl_id, MPI_Comm *comm, MPI_info *info)</div>
<div class="ttc" id="agroup___f_a_p_l_html_ga5d9e4b9f27791ccf19484a898f3fd6fa"><div class="ttname"><a href="group___f_a_p_l.html#ga5d9e4b9f27791ccf19484a898f3fd6fa">H5Pget_fapl_mpio</a></div><div class="ttdeci">H5_DLL herr_t H5Pget_fapl_mpio(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info)</div><div class="ttdoc">Returns MPI IO communicator information.</div></div>
<div class="ttc" id="agroup___f_a_p_l_html_gaa0204810c1fea1667d62cf7c176416ff"><div class="ttname"><a href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff">H5Pset_fapl_mpio</a></div><div class="ttdeci">H5_DLL herr_t H5Pset_fapl_mpio(hid_t fapl_id, MPI_Comm comm, MPI_Info info)</div><div class="ttdoc">Stores MPI IO communicator information to the file access property list.</div></div>
</div><!-- fragment --><p>The file access properties managed by <a class="el" href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff" title="Stores MPI IO communicator information to the file access property list.">H5Pset_fapl_mpio</a> and retrieved by <a class="el" href="group___f_a_p_l.html#ga5d9e4b9f27791ccf19484a898f3fd6fa" title="Returns MPI IO communicator information.">H5Pget_fapl_mpio</a> are the MPI communicator, comm, and the MPI info object, info. comm and info are used for file open. info is an information object much like an HDF5 property list. Both are defined in MPI_FILE_OPEN of MPI.</p>
<p>The communicator and the info object are saved in the file access property list fapl_id. fapl_id can then be passed to MPI_FILE_OPEN to create and/or open the file.</p>
<p><a class="el" href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff" title="Stores MPI IO communicator information to the file access property list.">H5Pset_fapl_mpio</a> and <a class="el" href="group___f_a_p_l.html#ga5d9e4b9f27791ccf19484a898f3fd6fa" title="Returns MPI IO communicator information.">H5Pget_fapl_mpio</a> are available only in the parallel HDF5 Library and are not collective functions. The Parallel driver is available only in the parallel HDF5 Library.</p>
<p>Additional parameters may be added to these functions in the future.</p>
<h2><a class="anchor" id="subsec_file_examples"></a>
Code Examples for Opening and Closing Files</h2>
<h3><a class="anchor" id="subsubsec_file_examples_trunc"></a>
Example Using the H5F_ACC_TRUNC Flag</h3>
<p>The following example uses the <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> flag when it creates a new file. The default file creation and file access properties are also used. Using <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> means the function will look for an existing file with the name specified by the function. In this case, that name is FILE. If the function does not find an existing file, it will create one. If it does find an existing file, it will empty the file in preparation for a new set of data. The identifier for the "new" file will be passed back to the application program. For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="#subsec_file_access_modes">File Access Modes</a>.</dd></dl>
<p><em>Creating a file with default creation and access properties</em> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file; <span class="comment">// identifier</span></div>
<div class="line"> </div>
<div class="line"><span class="comment">// Create a new file using H5F_ACC_TRUNC access, default</span></div>
<div class="line"><span class="comment">// file creation properties, and default file access</span></div>
<div class="line"><span class="comment">// properties.</span></div>
<div class="line">file = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a>(FILE, <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"><span class="comment">// Close the file.</span></div>
<div class="line">status = <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file);</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><!-- fragment --><h3><a class="anchor" id="subsubsec_file_examples_props"></a>
Example with the File Creation Property List</h3>
<p>The example below shows how to create a file with 64-bit object offsets and lengths.</p>
<p><em>Creating a file with 64-bit offsets</em> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> create_plist;</div>
<div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id;</div>
<div class="line"> </div>
<div class="line">create_plist = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a>(<a class="code hl_define" href="_h5_ppublic_8h.html#a206f334f1e6c973e1215a3148b45b977">H5P_FILE_CREATE</a>);</div>
<div class="line"><a class="code hl_function" href="group___f_c_p_l.html#gae5eb3ba16f063d151d1b56d33e0710a9">H5Pset_sizes</a>(create_plist, 8, 8);</div>
<div class="line">file_id = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a>(“test.h5”, <a class="code hl_define" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a>, create_plist, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>);</div>
<div class="line">.</div>
<div class="line">.</div>
<div class="line">.</div>
<div class="line"> </div>
<div class="line">H5Fclose(file_id);</div>
<div class="ttc" id="agroup___f_c_p_l_html_gae5eb3ba16f063d151d1b56d33e0710a9"><div class="ttname"><a href="group___f_c_p_l.html#gae5eb3ba16f063d151d1b56d33e0710a9">H5Pset_sizes</a></div><div class="ttdeci">herr_t H5Pset_sizes(hid_t plist_id, size_t sizeof_addr, size_t sizeof_size)</div><div class="ttdoc">Sets the byte size of the offsets and lengths used to address objects in an HDF5 file.</div></div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsec_file_examples_access"></a>
Example with the File Access Property List</h3>
<p>This example shows how to open an existing file for independent datasets access by MPI parallel I/O:</p>
<p><em>Opening an existing file for parallel I/O</em> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> access_plist;</div>
<div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id;</div>
<div class="line"> </div>
<div class="line">access_plist = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a>(<a class="code hl_define" href="_h5_ppublic_8h.html#a60ec2d4334addfc0eda89614598ee38e">H5P_FILE_ACCESS</a>);</div>
<div class="line">H5Pset_fapl_mpi(access_plist, MPI_COMM_WORLD, MPI_INFO_NULL);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// H5Fopen must be called collectively</span></div>
<div class="line">file_id = <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a>(“test.h5”, <a class="code hl_define" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a>, access_plist);</div>
<div class="line">.</div>
<div class="line">.</div>
<div class="line">.</div>
<div class="line"> </div>
<div class="line"><span class="comment">// H5Fclose must be called collectively</span></div>
<div class="line">H5Fclose(file_id);</div>
<div class="ttc" id="a_h5_fpublic_8h_html_a402673dec5c537b27a49a9a8bd6140b4"><div class="ttname"><a href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a></div><div class="ttdeci">#define H5F_ACC_RDWR</div><div class="ttdef"><b>Definition</b> H5Fpublic.h:49</div></div>
</div><!-- fragment --><h2><a class="anchor" id="subsec_file_multiple"></a>
Working with Multiple HDF5 Files</h2>
<p>Multiple HDF5 files can be associated so that the files can be worked with as though all the information is in a single HDF5 file. A temporary association can be set up by means of the <a class="el" href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b" title="Mounts an HDF5 file.">H5Fmount</a> function. A permanent association can be set up by means of the external link function <a class="el" href="group___h5_l.html#ga15dfaeb9b1c0b3136533cb97ee45e683" title="Creates an external link, a soft link to an object in a different file.">H5Lcreate_external</a>.</p>
<p>The purpose of this section is to describe what happens when the <a class="el" href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b" title="Mounts an HDF5 file.">H5Fmount</a> function is used to mount one file on another.</p>
<p>When a file is mounted on another, the mounted file is mounted at a group, and the root group of the mounted file takes the place of that group until the mounted file is unmounted or until the files are closed.</p>
<p>The figure below shows two files before one is mounted on the other. File1 has two groups and three datasets. The group that is the target of the A link has links, Z and Y, to two of the datasets. The group that is the target of the B link has a link, W, to the other dataset. File2 has three groups and three datasets. The groups in File2 are the targets of the AA, BB, and CC links. The datasets in File2 are the targets of the ZZ, YY, and WW links.</p>
<table class="doxtable">
<tr>
<td><div class="image">
<img src="Files_fig3.gif" alt=""/>
<div class="caption">
Two separate files</div></div>
</td></tr>
</table>
<p>The figure below shows the two files after File2 has been mounted File1 at the group that is the target of the B link.</p>
<table class="doxtable">
<tr>
<td><div class="image">
<img src="Files_fig4.gif" alt=""/>
<div class="caption">
File2 mounted on File1</div></div>
</td></tr>
</table>
<p>Note: In the figure above, the dataset that is the target of the W link is not shown. That dataset is masked by the mounted file.</p>
<p>If a file is mounted on a group that has members, those members are hidden until the mounted file is unmounted. There are two ways around this if you need to work with a group member. One is to mount the file on an empty group. Another is to open the group member before you mount the file. Opening the group member will return an identifier that you can use to locate the group member.</p>
<p>The example below shows how <a class="el" href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b" title="Mounts an HDF5 file.">H5Fmount</a> might be used to mount File2 onto File1.</p>
<p><em>Using H5Fmount</em> </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b">H5Fmount</a>(loc_id, <span class="stringliteral">"/B"</span>, child_id, plist_id)</div>
<div class="ttc" id="agroup___h5_f_html_ga7c4865fd36ee25d839725252150bb53b"><div class="ttname"><a href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b">H5Fmount</a></div><div class="ttdeci">herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist)</div><div class="ttdoc">Mounts an HDF5 file.</div></div>
</div><!-- fragment --><p>Note: In the code example above, loc_id is the file identifier for File1, /B is the link path to the group where File2 is mounted, child_id is the file identifier for File2, and plist_id is a property list identifier. For more information, </p><dl class="section see"><dt>See also</dt><dd><a class="el" href="_h5_g__u_g.html#sec_group">HDF5 Groups</a>.</dd></dl>
<p>See the entries for <a class="el" href="group___h5_f.html#ga7c4865fd36ee25d839725252150bb53b" title="Mounts an HDF5 file.">H5Fmount</a>, <a class="el" href="group___h5_f.html#gae8f807d3f04a33f132ffb6c5295e897f" title="Unounts an HDF5 file.">H5Funmount</a>, and <a class="el" href="group___h5_l.html#ga15dfaeb9b1c0b3136533cb97ee45e683" title="Creates an external link, a soft link to an object in a different file.">H5Lcreate_external</a> in the HDF5 Reference Manual.</p>
<p>Previous Chapter <a class="el" href="_h5__u_g.html#sec_program">The HDF5 Library and Programming Model</a> - Next Chapter <a class="el" href="_h5_g__u_g.html#sec_group">HDF5 Groups</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>
|
