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
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
* This file contains public declarations for the H5D module.
*/
#ifndef H5Dpublic_H
#define H5Dpublic_H
/* System headers needed by this file */
/* Public headers needed by this file */
#include "H5public.h"
#include "H5Ipublic.h"
/*****************/
/* Public Macros */
/*****************/
/* Macros used to "unset" chunk cache configuration parameters */
#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT ((size_t)-1)
#define H5D_CHUNK_CACHE_NBYTES_DEFAULT ((size_t)-1)
#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0)
/**
* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts()
*/
#define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u)
/*******************/
/* Public Typedefs */
/*******************/
//! <!-- [H5D_layout_t_snip] -->
/**
* Values for the H5D_LAYOUT property
*/
typedef enum H5D_layout_t {
H5D_LAYOUT_ERROR = -1, /**< error */
H5D_COMPACT = 0, /**< raw data is small (< 64KB) */
H5D_CONTIGUOUS = 1, /**< contiguous layout */
H5D_CHUNKED = 2, /**< chunked or tiled layout */
H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */
H5D_NLAYOUTS = 4 /**< this one must be last! */
} H5D_layout_t;
//! <!-- [H5D_layout_t_snip] -->
//! <!-- [H5D_chunk_index_t_snip] -->
/**
* Types of chunk index data structures
*/
typedef enum H5D_chunk_index_t {
H5D_CHUNK_IDX_BTREE = 0, /**< v1 B-tree index (default) */
H5D_CHUNK_IDX_SINGLE =
1, /**< Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */
H5D_CHUNK_IDX_NONE = 2, /**< Implicit: No Index (#H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */
H5D_CHUNK_IDX_FARRAY = 3, /**< Fixed array (for 0 unlimited dims) */
H5D_CHUNK_IDX_EARRAY = 4, /**< Extensible array (for 1 unlimited dim) */
H5D_CHUNK_IDX_BT2 = 5, /**< v2 B-tree index (for >1 unlimited dims) */
H5D_CHUNK_IDX_NTYPES /**< This one must be last! */
} H5D_chunk_index_t;
//! <!-- [H5D_chunk_index_t_snip] -->
//! <!-- [H5D_alloc_time_t_snip] -->
/**
* Values for the space allocation time property
*/
typedef enum H5D_alloc_time_t {
H5D_ALLOC_TIME_ERROR = -1, /**< Error */
H5D_ALLOC_TIME_DEFAULT = 0, /**< Default (layout dependent) */
H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */
H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */
H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */
} H5D_alloc_time_t;
//! <!-- [H5D_alloc_time_t_snip] -->
//! <!-- [H5D_space_status_t_snip] -->
/**
* Values for the status of space allocation
*/
typedef enum H5D_space_status_t {
H5D_SPACE_STATUS_ERROR = -1, /**< Error */
H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */
H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been partially allocated for this dataset.
(Used only for datasets with chunked storage.) */
H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been allocated for this dataset. */
} H5D_space_status_t;
//! <!-- [H5D_space_status_t_snip] -->
//! <!-- [H5D_fill_time_t_snip] -->
/**
* Values for time of writing fill value property
*/
typedef enum H5D_fill_time_t {
H5D_FILL_TIME_ERROR = -1, /**< Error */
H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */
H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */
H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */
} H5D_fill_time_t;
//! <!-- [H5D_fill_time_t_snip] -->
//! <!-- [H5D_fill_value_t_snip] -->
/**
* Values for fill value status
*/
typedef enum H5D_fill_value_t {
H5D_FILL_VALUE_ERROR = -1, /**< Error */
H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */
H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */
H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */
} H5D_fill_value_t;
//! <!-- [H5D_fill_value_t_snip] -->
//! <!-- [H5D_vds_view_t_snip] -->
/**
* Values for VDS bounds option
*/
typedef enum H5D_vds_view_t {
H5D_VDS_ERROR = -1, /**< Error */
H5D_VDS_FIRST_MISSING = 0, /**< Include all data before the first missing mapped data */
H5D_VDS_LAST_AVAILABLE = 1 /**< Include all available mapped data */
} H5D_vds_view_t;
//! <!-- [H5D_vds_view_t_snip] -->
//! <!-- [H5D_append_cb_t_snip] -->
/**
* \brief Callback for H5Pset_append_flush()
*
* \dset_id{dataset_id}
* \param[in] cur_dims The current extent of the dataset's dimensions
* \param[in,out] op_data User context
*
* \return \herr_t
*
*/
typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data);
//! <!-- [H5D_append_cb_t_snip] -->
//! <!-- [H5D_operator_t_snip] -->
/**
* \brief Callback for H5Diterate()
*
* \param[in,out] elem Pointer to the memory buffer containing the current dataset
* element
* \param[in] type_id Datatype identifier of the elements stored in \p elem
* \param[in] ndim Number of dimensions for the \p point array
* \param[in] point Array containing the location of the element within
* the original dataspace
* \param[in,out] operator_data Pointer to any user-defined data associated with
* the operation
* \return \herr_t_iter
*
*/
typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point,
void *operator_data);
//! <!-- [H5D_operator_t_snip] -->
//! <!-- [H5D_scatter_func_t_snip] -->
/**
* \brief Callback for H5Dscatter()
*
* \param[out] src_buf Pointer to the buffer holding the next set of elements to
* scatter. On entry, the value of where \p src_buf points to
* is undefined. The callback function should set \p src_buf
* to point to the next set of elements.
* \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf.
* On entry, the value where \p src_buf_bytes_used points
* to is undefined. The callback function should set
* \p src_buf_bytes_used to the of valid bytes in \p src_buf.
* This number must be a multiple of the datatype size.
* \param[in,out] op_data User-defined pointer to data required by the callback
* function. A pass-through of the \p op_data pointer provided
* with the H5Dscatter() function call.
* \return herr_t
*
* \details The callback function should always return at least one
* element in \p src_buf, and must not return more elements
* than are remaining to be scattered. This function will be
* repeatedly called until all elements to be scattered have
* been returned. The callback function should return zero (0)
* to indicate success, and a negative value to indicate failure.
*
*/
typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/,
void *op_data);
//! <!-- [H5D_scatter_func_t_snip] -->
//! <!-- [H5D_gather_func_t_snip] -->
/**
* \brief Callback for H5Dgather()
*
* \param[in] dst_buf Pointer to the destination buffer which has been filled
* with the next set of elements gathered. This will always
* be identical to the \p dst_buf passed to H5Dgather()
* \param[in] dst_buf_bytes_used Pointer to the number of valid bytes in
* \p dst_buf. This number must be a multiple of
* the datatype size.
* \param[in,out] op_data User-defined pointer to data required by the callback
* function; a pass-through of the \p op_data pointer
* provided with the H5Dgather() function call.
* \returns \herr_t
*
* \details The callback function should process, store, or otherwise make use
* of the data returned in dst_buf before it returns, because the
* buffer will be overwritten unless it is the last call to the
* callback. This function will be repeatedly called until all gathered
* elements have been passed to the callback in dst_buf. The callback
* function should return zero (0) to indicate success, and a negative
* value to indicate failure.
*
*/
typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data);
//! <!-- [H5D_gather_func_t_snip] -->
//! <!-- [H5D_chunk_iter_op_t_snip] -->
/**
* \brief Callback for H5Dchunk_iter()
*
* \param[in] offset Logical position of the chunk’s first element in units of dataset elements
* \param[in] filter_mask Bitmask indicating the filters used when the chunk was written
* \param[in] addr Chunk address in the file
* \param[in] size Chunk size in bytes, 0 if the chunk does not exist
* \param[in,out] op_data Pointer to any user-defined data associated with
* the operation.
* \returns \li Zero (#H5_ITER_CONT) causes the iterator to continue, returning
* zero when all elements have been processed.
* \li A positive value (#H5_ITER_STOP) causes the iterator to
* immediately return that value, indicating short-circuit success.
* \li A negative (#H5_ITER_ERROR) causes the iterator to immediately
* return that value, indicating failure.
*/
typedef int (*H5D_chunk_iter_op_t)(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t size,
void *op_data);
//! <!-- [H5D_chunk_iter_op_t_snip] -->
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
#ifdef __cplusplus
extern "C" {
#endif
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Creates a new dataset and links it into the file
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \lcpl_id
* \dcpl_id
* \dapl_id
*
* \return \hid_t{dataset}
*
* \details H5Dcreate2() creates a new dataset named \p name at
* the location specified by \p loc_id, and associates constant
* and initial persistent properties with that dataset, including
* the datatype \p dtype_id, the dataspace \p space_id, and
* other properties as specified by the dataset creation property
* list \p dcpl_id and the access property list \p dapl_id,
* respectively. Once created, the dataset is opened for access.
*
* \p loc_id may specify a file, group, dataset, named datatype,
* or attribute. If an attribute, dataset, or named datatype is
* specified then the dataset will be created at the location
* where the attribute, dataset, or named datatype is attached.
*
* \p name may be either an absolute path in the file or a relative
* path from \p loc_id naming the dataset.
*
* If \p dtype_id is a committed datatype, and if the file location
* associated with the committed datatype is different from the
* file location where the dataset will be created, the datatype
* is copied and converted to a transient type.
*
* The link creation property list, \p lcpl_id, governs creation
* of the link(s) by which the new dataset is accessed and the
* creation of any intermediate groups that may be missing.
*
* The datatype and dataspace properties and the dataset creation
* and access property lists are attached to the dataset, so the
* caller may derive new datatypes, dataspaces, and creation and
* access properties from the old ones and reuse them in calls to
* create additional datasets. Once created, the dataset can be
* read from or written to. Reading data from a dataset that was
* not previously written, the HDF5 library will return default
* or user-defined fill values.
*
* \par Example
* \snippet H5D_examples.c create
*
* \since 1.8.0
*
* \see H5Dopen2(), H5Dclose(), H5Tset_size()
*
*/
H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id,
hid_t dcpl_id, hid_t dapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Creates a dataset in a file without linking it into the file
* structure
*
* \fgdta_loc_id
* \type_id
* \space_id
* \dcpl_id
* \dapl_id
*
* \return \hid_t{dataset}
*
* \details H5Dcreate_anon() creates a dataset in the file specified
* by \p loc_id.
*
* \p loc_id may specify a file, group, dataset, named datatype,
* or attribute. If an attribute, dataset, or named datatype is
* specified then the dataset will be created at the location
* where the attribute, dataset, or named datatype is attached.
*
* The dataset’s datatype and dataspace are specified by
* \p type_id and \p space_id, respectively. These are the
* datatype and dataspace of the dataset as it will exist in
* the file, which may differ from the datatype and dataspace
* in application memory.
*
* H5Dcreate_anon() returns a new dataset identifier. Using
* this identifier, the new dataset must be linked into the
* HDF5 file structure with H5Olink() or it will be deleted
* when the file is closed.
*
* \since 1.8.0
*
* \see H5Olink(), H5Dcreate()
*
*/
H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Opens an existing dataset
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to open
* \dapl_id
*
* \return \hid_t{dataset}
*
* \details H5Dopen2() opens the existing dataset specified
* by a location identifier and name, \p loc_id and \p name,
* respectively.
*
* \p loc_id may specify a file, group, dataset, named datatype,
* or attribute. If an attribute, dataset, or named datatype is
* specified then the dataset will be opened at the location
* where the attribute, dataset, or named datatype is attached.
*
* \since 1.8.0
*
* \see H5Dcreate2(), H5Dclose()
*
*/
H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id);
/**
* --------------------------------------------------------------------------
*\ingroup H5D
*
* \brief Returns an identifier for a copy of the dataspace for a dataset
*
* \dset_id
*
* \return \hid_t{dataspace}
*
* \details H5Dget_space() makes a copy of the dataspace of
* the dataset specified by \p dset_id. The function returns an
* identifier for the new copy of the dataspace.
*
* A dataspace identifier returned from this function should
* be released with H5Sclose() when the identifier is no longer
* needed so that resource leaks will not occur.
*
* \par Example
* \snippet H5D_examples.c update
*
* \see H5Sclose()
*
*/
H5_DLL hid_t H5Dget_space(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Determines whether space has been allocated for a dataset
*
* \dset_id
* \param[out] allocation Space allocation status
*
* \return \herr_t
*
* \details H5Dget_space_status() determines whether space has been allocated
* for the dataset \p dset_id.
*
* \since 1.6.0
*
*/
H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Returns an identifier for a copy of the datatype for a dataset
*
* \dset_id
*
* \return \hid_t{datatype}
*
* \details H5Dget_type() returns an identifier of a copy of
* the datatype for a dataset.
*
* If a dataset has a named datatype, then an identifier to the
* opened datatype is returned. Otherwise, the returned datatype
* is read-only.
*
*/
H5_DLL hid_t H5Dget_type(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Returns an identifier for a copy of the dataset creation
* property list for a dataset
*
* \dset_id
*
* \return \hid_t{dataset creation property list}
*
* \details H5Dget_create_plist() returns an identifier for
* a copy of the dataset creation property list associated with
* the dataset specified by \p dset_id.
*
* The creation property list identifier should be released with
* H5Pclose() to prevent resource leaks.
*
*/
H5_DLL hid_t H5Dget_create_plist(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Returns the dataset access property list associated with
* a dataset
*
* \dset_id
*
* \return \hid_t{dataset access property list}
*
* \details H5Dget_access_plist() returns a copy of the
* dataset access property list used to open the specified
* dataset, \p dset_id. Modifications to the returned property
* list will have no effect on the dataset it was retrieved from.
*
* The chunk cache parameters in the returned property lists will
* be those used by the dataset. If the properties in the file
* access property list were used to determine the dataset's
* chunk cache configuration, then those properties will be
* present in the returned dataset access property list. If
* the dataset does not use a chunked layout, then the chunk
* cache properties will be set to the default. The chunk cache
* properties in the returned list are considered to be “set”,
* and any use of this list will override the corresponding
* properties in the file’s file access property list.
*
* All link access properties in the returned list will be set
* to the default values.
*
* \since 1.8.3
*
*/
H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Returns the amount of storage allocated for a dataset
*
* \dset_id
*
* \return Returns the amount of storage space, in bytes, or 0 (zero).
*
* \details H5Dget_storage_size() returns the amount of storage,
* in bytes, that is allocated in the file for the raw data of
* the dataset specified by \p dset_id.
* H5Dget_storage_size() reports only the space required to store
* the dataset elements, excluding any metadata.
* \li For contiguous datasets, the returned size equals the current
* allocated size of the raw data.
* \li For unfiltered chunked datasets, the returned size is the
* number of allocated chunks times the chunk size.
* \li For filtered chunked datasets, the returned size is the
* space required to store the filtered data. For example, if a
* compression filter is in use, H5Dget_storage_size() will return
* the total space required to store the compressed chunks.
*
* \note Note that H5Dget_storage_size() is not generally an
* appropriate function to use when determining the amount
* of memory required to work with a dataset. In such
* circumstances, you must determine the number of data
* points in a dataset and the size of an individual dataset
* element. H5Sget_simple_extent_npoints() and H5Tget_size()
* can be used to calculate that amount.
*
* \warning H5Dget_storage_size() does not differentiate between 0 (zero),
* the value returned for the storage size of a dataset
* with no stored values, and 0 (zero), the value returned to
* indicate an error.
*
*
*/
H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Returns the amount of storage allocated within the file for a
* raw data chunk in a dataset
*
* \dset_id
* \param[in] offset Logical offset in the dataset for the chunk to query
* \param[out] chunk_bytes The size in bytes for the chunk
*
* \return \herr_t
*
* \details H5Dget_chunk_storage_size() returns the size in bytes
* allocated in the file for a raw data chunk as specified by
* its logical \p offset in the dataset \p dset_id. The size is
* returned in \p chunk_nbytes. It is the size of the compressed
* data if the chunk is filtered and the size may be zero if no
* storage is allocated yet for the dataset.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hsize_t *chunk_bytes);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Retrieves number of chunks that have nonempty intersection with a
* specified selection
*
* \dset_id
* \param[in] fspace_id File dataspace selection identifier
* \param[out] nchunks Number of chunks in the selection
*
* \return \herr_t
*
* \details H5Dget_num_chunks() retrieves the number of chunks
* nchunks in a set of selected elements specified by \p fspace_id
* for a dataset specified by the identifier \p dset_id. If \p
* fspace_id is #H5S_ALL, the function will retrieve the total
* number of chunks stored for the dataset.
*
* \p fspace_id specifies the file dataspace selection. It is
* intended to take #H5S_ALL for specifying the current selection.
*
* \note Please be aware that this function currently does not
* support non-trivial selections, thus \p fspace_id has no
* effect. Also, the implementation does not handle the #H5S_ALL
* macro correctly. As a workaround, application can get
* the dataspace for the dataset using H5Dget_space() and pass that
* in for \p fspace_id. This will be fixed in a future release.
*
* \since 1.10.5
*
*/
H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Retrieves information about a chunk specified by its coordinates
*
* \dset_id
* \param[in] offset Logical position of the chunk’s first element in units of dataset elements
* \param[out] filter_mask Bitmask indicating the filters used when the chunk was written
* \param[out] addr Chunk address in the file
* \param[out] size Chunk size in bytes, 0 if the chunk does not exist
*
* \return \herr_t
*
* \details H5Dget_chunk_info_by_coord() retrieves the \p filter_mask, \p size,
* and \p addr for a chunk in the dataset specified by \p dset_id,
* using the coordinates specified by \p offset.
*
* If the queried chunk does not exist in the file, \p size will
* be set to 0, \p addr to \c HADDR_UNDEF, and the buffer \p
* filter_mask will not be modified.
*
* \p offset is a pointer to a one-dimensional array with a size
* equal to the dataset’s rank. Each element is the logical
* position of the chunk’s first element in a dimension.
*
* \since 1.10.5
*
*/
H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, unsigned *filter_mask,
haddr_t *addr, hsize_t *size);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Iterate over all chunks of a chunked dataset
*
* \dset_id
* \param[in] dxpl_id Identifier of a transfer property list
* \param[in] cb User callback function, called for every chunk.
* \param[in] op_data User-defined pointer to data required by op
*
* \return \herr_t
*
* \details H5Dchunk_iter iterates over all chunks in the dataset, calling the
* user supplied callback with the details of the chunk and the supplied
* context \p op_data.
*
* \par Example
* For each chunk, print the allocated chunk size (0 for un-allocated chunks).
* \snippet H5D_examples.c H5Dchunk_iter_cb
* Iterate over all chunked datasets and chunks in a file.
* \snippet H5D_examples.c H5Ovisit_cb
*
* \since 1.12.3
*
*/
H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Retrieves information about a chunk specified by its index
*
* \dset_id
* \param[in] fspace_id File dataspace selection identifier (See Note below)
* \param[in] chk_idx Index of the chunk
* \param[out] offset Logical position of the chunk’s first element in units of dataset elements
* \param[out] filter_mask Bitmask indicating the filters used when the chunk was written
* \param[out] addr Chunk address in the file
* \param[out] size Chunk size in bytes, 0 if the chunk does not exist
*
* \return \herr_t
*
* \details H5Dget_chunk_info() retrieves the offset coordinates,
* \p offset, filter mask, \p filter_mask, size, \p size, and address
* \p addr for the dataset specified by the identifier \p dset_id and the chunk
* specified by the index \p index. The chunk belongs to a set of
* chunks in the selection specified by \p fspace_id. If the queried
* chunk does not exist in the file, the size will be set to 0 and
* address to #HADDR_UNDEF. The value pointed to by filter_mask will
* not be modified. \c NULL can be passed in for any \p out parameters.
*
* \p chk_idx is the chunk index in the selection. The index value
* may have a value of 0 up to the number of chunks stored in
* the file that have a nonempty intersection with the file
* dataspace selection
*
* \note As of 1.10.5, the dataspace intersection is not yet
* supported, hence, the index is of all the written chunks.
*
* \p fspace_id specifies the file dataspace selection. It is
* intended to take #H5S_ALL for specifying the current selection.
*
* \note Please be aware that this function currently does not
* support non-trivial selections, thus \p fspace_id has no
* effect. Also, the implementation does not handle the #H5S_ALL
* macro correctly. As a workaround, an application can get
* the dataspace for the dataset using H5Dget_space() and pass that
* in for \p fspace_id. This will be fixed in a future release.
*
* \since 1.10.5
*
*/
H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, hsize_t *offset,
unsigned *filter_mask, haddr_t *addr, hsize_t *size);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Returns dataset address in file
*
* \dset_id
*
* \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF,
* a negative value.
*
* \details H5Dget_offset() returns the address in the file of
* the dataset, \p dset_id. That address is expressed as the
* offset in bytes from the beginning of the file.
*
* \since 1.6.0
*
*/
H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Reads raw data from a dataset into a provided buffer
*
* \dset_id Identifier of the dataset to read from
* \param[in] mem_type_id Identifier of the memory datatype
* \param[in] mem_space_id Identifier of the memory dataspace
* \param[in] file_space_id Identifier of the dataset's dataspace in the file
* \param[in] dxpl_id Identifier of a transfer property list
* \param[out] buf Buffer to receive data read from file
*
* \return \herr_t
*
* \details H5Dread() reads a dataset, specified by its identifier
* \p dset_id, from the file into an application memory buffer \p
* buf. Data transfer properties are defined by the argument \p
* dxpl_id. The memory datatype of the (partial) dataset
* is identified by the identifier \p mem_type_id. The part
* of the dataset to read is defined by \p mem_space_id and \p
* file_space_id.
*
* \p file_space_id is used to specify only the selection within
* the file dataset's dataspace. Any dataspace specified in \p
* file_space_id is ignored by the library and the dataset's
* dataspace is always used. \p file_space_id can be the constant
* #H5S_ALL, which indicates that the entire file dataspace,
* as defined by the current dimensions of the dataset, is to
* be selected.
*
* \p mem_space_id is used to specify both the memory dataspace
* and the selection within that dataspace. \p mem_space_id can
* be the constant #H5S_ALL, in which case the file dataspace is
* used for the memory dataspace and the selection defined with \p
* file_space_id is used for the selection within that dataspace.
*
* The number of elements selected in the memory dataspace \Emph{must}
* be equal to the number of elements selected in the file dataspace.
*
* The behavior of the library for the various combinations of
* valid dataspace identifiers and #H5S_ALL for the \p mem_space_id
* and the \p file_space_id parameters is described below:
*
* <table>
* <tr>
* <th>mem_space_id</th>
* <th>file_space_id</th>
* <th>Behavior</th>
* </tr>
* <tr>
* <td>valid dataspace ID</td>
* <td>valid dataspace ID</td>
* <td>\p mem_space_id specifies the memory dataspace and the
* selection within it. \p file_space_id specifies the
* selection within the file dataset's dataspace.</td>
* </tr>
* <tr>
* <td>#H5S_ALL</td>
* <td>valid dataspace ID</td>
* <td>The file dataset's dataspace is used for the memory
* dataspace and the selection specified with \p file_space_id
* specifies the selection within it. The combination of the
* file dataset's dataspace and the selection from
* \p file_space_id is used for memory also.</td>
* </tr>
* <tr>
* <td>valid dataspace ID</td>
* <td>#H5S_ALL</td>
* <td>\p mem_space_id specifies the memory dataspace and the
* selection within it. The selection within the file
* dataset's dataspace is set to the "all" selection.</td>
* </tr>
* <tr>
* <td>#H5S_ALL</td>
* <td>#H5S_ALL</td>
* <td>The file dataset's dataspace is used for the memory
* dataspace and the selection within the memory dataspace
* is set to the "all" selection. The selection within the
* file dataset's dataspace is set to the "all" selection.</td>
* </tr>
* </table>
*
* \note If no storage space was allocated for the dataset
* and a fill value is defined, the returned buffer \p buf
* is filled with the fill value.
*
* \par Example
* \snippet H5D_examples.c read
*
*/
H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id,
hid_t dxpl_id, void *buf /*out*/);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Writes raw data from a buffer to a dataset
*
* \param[in] dset_id Identifier of the dataset to read from
* \param[in] mem_type_id Identifier of the memory datatype
* \param[in] mem_space_id Identifier of the memory dataspace
* \param[in] file_space_id Identifier of the dataset's dataspace in the file
* \dxpl_id
* \param[out] buf Buffer with data to be written to the file
*
* \return \herr_t
*
* \details H5Dwrite() writes a (partial) dataset, specified by
* its identifier \p dset_id, from the application memory buffer \p
* buf into the file. Data transfer properties are defined by the
* argument \p dxpl_id. The memory datatype of the (partial)
* dataset is identified by the identifier \p mem_type_id. The
* part of the dataset to write is defined by \p mem_space_id
* and \p file_space_id.
*
* If \p mem_type_id is either a fixed-length or variable-length
* string, it is important to set the string length when defining
* the datatype. String datatypes are derived from #H5T_C_S1
* (or #H5T_FORTRAN_S1 for Fortran codes), which defaults
* to 1 character in size. See H5Tset_size() and Creating
* variable-length string datatypes.
*
* \p file_space_id is used to specify only the selection within
* the file dataset's dataspace. Any dataspace specified in \p
* file_space_id is ignored by the library and the dataset's
* dataspace is always used. \p file_space_id can be the constant
* #H5S_ALL, which indicates that the entire file dataspace,
* as defined by the current dimensions of the dataset, is to
* be selected.
*
* \p mem_space_id is used to specify both the memory dataspace
* and the selection within that dataspace. mem_space_id can be
* the constant #H5S_ALL, in which case the file dataspace is
* used for the memory dataspace and the selection defined with \p
* file_space_id is used for the selection within that dataspace.
*
* The behavior of the library for the various combinations of
* valid dataspace IDs and #H5S_ALL for the mem_space_id and
* thefile_space_id parameters is described below:
*
* <table>
* <tr><th>\c mem_space_id</th>
* <th>\c file_space_id</th>
* <th>Behavior</th></tr>
* <tr><td>valid dataspace ID</td>
* <td>valid dataspace ID</td>
* <td>\p mem_space_id specifies the memory dataspace and the
* selection within it. \p file_space_id specifies the
* selection within the file dataset's dataspace.</td></tr>
* <tr><td>#H5S_ALL</td>
* <td>valid dataspace ID</td>
* <td>The file dataset's dataspace is used for the memory
* dataspace and the selection specified with \p file_space_id
* specifies the selection within it. The combination of the
* file dataset's dataspace and the selection from \p
* file_space_id is used for memory also. valid dataspace
* ID</td></tr>
* <tr><td>valid dataspace ID</td>
* <td>#H5S_ALL</td>
* <td>\p mem_space_id specifies the memory dataspace and the
* selection within it. The selection within the file
* dataset's dataspace is set to "all" selection.</td></tr>
* <tr><td>#H5S_ALL</td>
* <td>#H5S_ALL</td>
* <td>The file dataset's dataspace is used for the memory
* dataspace and the selection within the memory dataspace is
* set to the "all" selection. The selection within the file
* dataset's dataspace is set to the "all"
* selection.</td></tr>
* </table>
* Setting an "all" selection indicates that the entire dataspace,
* as defined by the current dimensions of a dataspace, will
* be selected. The number of elements selected in the memory
* dataspace must match the number of elements selected in the
* file dataspace.
*
* \p dxpl_id can be the constant #H5P_DEFAULT, in which
* case the default data transfer properties are used.
*
* Writing to a dataset will fail if the HDF5 file was not opened
* with write access permissions.
*
* If the dataset's space allocation time is set to
* #H5D_ALLOC_TIME_LATE or #H5D_ALLOC_TIME_INCR and the space for
* the dataset has not yet been allocated, that space is allocated
* when the first raw data is written to the dataset. Unused space
* in the dataset will be written with fill values at the same
* time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET
* or #H5D_FILL_TIME_ALLOC.
*
* \par_compr_note
*
* \attention If a dataset's storage layout is 'compact', care must be
* taken when writing data to the dataset in parallel. A compact
* dataset's raw data is cached in memory and may be flushed
* to the file from any of the parallel processes, so parallel
* applications should always attempt to write identical data to
* the dataset from all processes.
*
* \par Example
* \snippet H5D_examples.c update
*
* \see H5Pset_fill_time(), H5Pset_alloc_time()
*
*/
H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id,
hid_t dxpl_id, const void *buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Writes a raw data chunk from a buffer directly to a dataset in a file
*
* \dset_id
* \dxpl_id
* \param[in] filters Mask for identifying the filters in use
* \param[in] offset Logical position of the chunk’s first element in the
* dataspace
* \param[in] data_size Size of the actual data to be written in bytes
* \param[in] buf Buffer containing data to be written to the chunk
*
* \return \herr_t
*
* \details H5Dwrite_chunk() writes a raw data chunk as specified
* by its logical offset \p offset in a chunked dataset \p dset_id
* from the application memory buffer \p buf to the dataset in
* the file. Typically, the data in \p buf is preprocessed in
* memory by a custom transformation, such as compression. The
* chunk will bypass the library’s internal data transfer
* pipeline, including filters, and will be written directly to
* the file. Only one chunk can be written with this function.
*
* \p filters is a mask providing a record of which filters are
* used with the the chunk. The default value of the mask is
* zero (0), indicating that all enabled filters are applied. A
* filter is skipped if the bit corresponding to the filter’s
* position in the pipeline (0 ≤ position < 32) is turned on.
* This mask is saved with the chunk in the file.
*
* \p offset is an array specifying the logical position of the
* first element of the chunk in the dataset’s dataspace. The
* length of the offset array must equal the number of dimensions,
* or rank, of the dataspace. The values in offset must not exceed
* the dimension limits and must specify a point that falls on
* a dataset chunk boundary.
*
* \p data_size is the size in bytes of the chunk, representing
* the number of bytes to be read from the buffer \p buf. If the
* data chunk has been precompressed, \p data_size should be the
* size of the compressed data.
*
* \p buf is the memory buffer containing data to be written to
* the chunk in the file.
*
* \attention Exercise caution when using H5Dread_chunk() and
* H5Dwrite_chunk(), as they read and write data chunks directly
* in a file. H5Dwrite_chunk() bypasses hyperslab selection, the
* conversion of data from one datatype to another, and the filter
* pipeline to write the chunk. Developers should have experience
* with these processes before using this function.
*
* \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported
* with parallel HDF5 and do not support variable-length types.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset,
size_t data_size, const void *buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Reads a raw data chunk directly from a dataset in a file into
* a buffer
*
* \dset_id
* \dxpl_id
* \param[in] offset Logical position of the chunk’s first element in the
* dataspace
* \param[in,out] filters Mask for identifying the filters in use
* \param[out] buf Buffer containing data to be written to the chunk
*
* \return \herr_t
*
* \details H5Dread_chunk() reads a raw data chunk as specified by
* its logical offset \p offset in a chunked dataset \p dset_id
* from the dataset in the file into the application memory
* buffer \p buf. The data in \p buf is read directly from the
* file bypassing the library’s internal data transfer pipeline,
* including filters.
*
* \p offset is an array specifying the logical position of the
* first element of the chunk in the dataset’s dataspace. The
* length of the \p offset array must equal the number of dimensions,
* or rank, of the dataspace. The values in \p offset must not exceed
* the dimension limits and must specify a point that falls on
* a dataset chunk boundary.
*
* The mask \p filters indicates which filters were used when the
* chunk was written. A zero value (all bits 0) indicates that all
* enabled filters are applied on the chunk. A filter is skipped if
* the bit corresponding to the filter’s position in the pipeline
* (0 ≤ position < 32) is turned on.
*
* \p buf is the memory buffer containing the chunk read from
* the dataset in the file.
*
* \attention Exercise caution when using H5Dread_chunk() and
* H5Dwrite_chunk(), as they read and write data chunks directly
* in a file. H5Dwrite_chunk() bypasses hyperslab selection, the
* conversion of data from one datatype to another, and the filter
* pipeline to write the chunk. Developers should have experience
* with these processes before using this function. Please see
* Using the Direct Chunk Write Function for more information.
*
* \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported
* with parallel HDF5 and do not support variable-length datatypes.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters,
void *buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Iterates over all selected elements in a dataspace
*
* \param[in,out] buf Buffer containing the elements to iterate over
* \type_id
* \space_id
* \param[in] op Function pointer
* \param[in,out] operator_data User-defined data
*
* \return \success{The return value of the first operator that returns
* non-zero, or zero if all members were processed with no
* operator returning non-zero.}
* \return \failure{Negative if an error occurs in the library, or the negative
* value returned by one of the operators.}
*
* \details H5Diterate() iterates over all the data elements
* in the memory buffer \p buf, executing the callback function
* \p op once for each such data element.
*
* \attention Unlike other HDF5 iterators, this iteration operation cannot
* be restarted at the point of exit; a second H5Diterate()
* call will always restart at the beginning.
*
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Diterate(void *buf, hid_t type_id, hid_t space_id, H5D_operator_t op, void *operator_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Determines the number of bytes required to store variable-length
* (VL) data
*
* \dset_id
* \type_id
* \space_id
* \param[out] size Size in bytes of the memory buffer required to store
* the VL data
*
* \return \herr_t
*
* \details H5Dvlen_get_buf_size() determines the number of bytes
* required to store the VL data from the dataset, using \p
* space_id for the selection in the dataset on disk and the \p
* type_id for the memory representation of the VL data in memory.
* \p size is returned with the number of bytes required to store
* the VL data in memory.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, hsize_t *size);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Fills dataspace elements with a fill value in a memory buffer
*
* \param[in] fill Pointer to the fill value to be used
* \param[in] fill_type_id Fill value datatype identifier
* \param[in,out] buf Pointer to the memory buffer containing the
* selection to be filled
* \param[in] buf_type_id Datatype of dataspace elements to be filled
* \space_id
*
* \return \herr_t
*
* \details H5Dfill() fills the dataspace selection, \p space_id, in memory
* with the fill value specified in \p fill. If \p fill is NULL,
* a fill value of 0 (zero) is used.
*
* \p fill_type_id specifies the datatype of the fill value.
* \p buf specifies the buffer in which the fill elements
* will be written. \p buf_type_id specifies the datatype of
* those data elements.
*
* \note Note that if the fill value datatype differs from the memory
* buffer datatype, the fill value will be converted to the memory
* buffer datatype before filling the selection.
*
* \note Applications sometimes write data only to portions of an
* allocated dataset. It is often useful in such cases to fill
* the unused space with a known fill value.
*
* \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(),
* H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon()
*
*/
H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Changes the sizes of a dataset’s dimensions
*
* \dset_id
* \param[in] size[] Array containing the new magnitude of each dimension
* of the dataset
*
* \return \herr_t
*
* \details H5Dset_extent() sets the current dimensions of the
* chunked dataset \p dset_id to the sizes specified in size.
*
* \p size is a 1-dimensional array with n elements, where \p n is
* the rank of the dataset’s current dataspace.
*
* This function can be applied to the following datasets:
* - A chunked dataset with unlimited dimensions
* - A chunked dataset with fixed dimensions if the new dimension
* sizes are less than the maximum sizes set with maxdims (see
* H5Screate_simple())
* - An external dataset with unlimited dimensions
* - An external dataset with fixed dimensions if the new dimension
* sizes are less than the maximum sizes set with \p maxdims
*
* Note that external datasets are always contiguous and can be
* extended only along the first dimension.
*
* Space on disk is immediately allocated for the new dataset extent if
* the dataset’s space allocation time is set to #H5D_ALLOC_TIME_EARLY.
*
* Fill values will be written to the dataset in either of the
* following situations, but not otherwise:
*
* - If the dataset’s fill time is set to #H5D_FILL_TIME_IFSET and a
* fill value is defined (see H5Pset_fill_time() and
* H5Pset_fill_value())
* - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC
* (see H5Pset_alloc_time())
*
* \note If the sizes specified in \p size array are smaller than the dataset’s
* current dimension sizes, H5Dset_extent() will reduce the dataset’s
* dimension sizes to the specified values. It is the user application’s
* responsibility to ensure that valuable data is not lost as
* H5Dset_extent() does not check.
*
* \note Except for external datasets, H5Dset_extent() is for use with
* chunked datasets only, not contiguous datasets.
*
* \note A call to H5Dset_extent() affects the dataspace of a dataset. If a
* dataspace handle was opened for a dataset prior to a call to
* H5Dset_extent() then that dataspace handle will no longer reflect the
* correct dataspace extent of the dataset. H5Dget_space() must be called
* (after closing the previous handle) to obtain the current dataspace
* extent.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Flushes all buffers associated with a dataset to disk
*
* \dset_id
*
* \return \herr_t
*
* \details H5Dflush() causes all buffers associated with a
* dataset to be immediately flushed to disk without removing
* the data from the cache.
*
* \note HDF5 does not possess full control over buffering.
* H5Dflush() flushes the internal HDF5 buffers and then asks the
* operating system (the OS) to flush the system buffers for the
* open files. After that, the OS is responsible for ensuring
* that the data is actually flushed to disk.
*
* \since 1.10.0
*
*/
H5_DLL herr_t H5Dflush(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Refreshes all buffers associated with a dataset
*
* \dset_id
*
* \return \herr_t
*
* \details H5Drefresh() causes all buffers associated with a
* dataset to be cleared and immediately re-loaded with updated
* contents from disk.
*
* This function essentially closes the dataset, evicts all
* metadata associated with it from the cache, and then re-opens
* the dataset. The reopened dataset is automatically re-registered
* with the same identifier.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Drefresh(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Scatters data into a selection within a memory buffer
*
* \param[in] op Callback function which provides data to be scattered
* \param[in] op_data User-defined pointer to data required by op
* \param[in] type_id Identifier for the datatype describing the data in
* both the source and destination buffers
* \param[in] dst_space_id Identifier for the dataspace for destination
* \param[out] dst_buf Destination buffer which the data will be scattered to
*
* \return \herr_t
*
* \details H5Dscatter() retrieves data from the supplied callback
* \p op and scatters it to the supplied buffer \p dst_buf in a
* manner similar to data being written to a dataset.
*
* \p dst_space_id is a dataspace which defines the extent of \p
* dst_buf and the selection within it to scatter the data to.
*
* \p type_id is the datatype of the data to be scattered in both
* the source and destination buffers.
*
* \p dst_buf must be at least as large as the number of elements
* in the extent of \p dst_space_id times the size in bytes of
* \p type_id.
*
* To retrieve the data to be scattered, H5Dscatter() repeatedly
* calls \p op, which should return a valid source buffer, until
* enough data to fill the selection has been retrieved.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hid_t dst_space_id,
void *dst_buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Gathers data from a selection within a memory buffer
* raw data chunk in a dataset
*
* \param[in] src_space_id Dataspace identifier for the source buffer
* \param[in] src_buf Source buffer which the data will be gathered from
* \param[in] type_id Datatype identifier for the source
* \param[in] dst_buf_size Size in bytes of \p dst_buf
* \param[out] dst_buf Destination buffer for the gathered data
* \param[in] op Callback function which handles the gathered data
* \param[in] op_data User-defined pointer to data required by \p op
*
* \return \herr_t
*
* \details H5Dgather() retrieves data from a selection within the supplied
* buffer src_buf and passes it to the supplied callback function
* \p op in a contiguous form.
*
* The dataspace \p src_space_id describes both the dimensions of
* the source buffer and the selection within the source buffer
* to gather data from.
*
* \p src_buf must be at least the size of the gathered data, that
* is, the number of elements in the extent of \p src_space_id
* times the size in bytes of \p type_id.
*
* The datatype \p type_id describes the data in both the source
* and destination buffers. This information is used to calculate
* the element size.
*
* The data is gathered into \p dst_buf, which needs to be large
* enough to hold all the data if the callback function \p op is
* not provided.
*
* \p op is a callback function which handles the gathered data.
* It is optional if \p dst_buf is large enough to hold all of the
* gathered data; required otherwise.
*
* If no callback function is provided, H5Dgather() simply gathers
* the data into \p dst_buf and returns. If a callback function is
* provided, H5Dgather() repeatedly gathers up to \p dst_buf_size
* bytes to process the serialized data.
*
* The callback function \p op should process, store, or otherwise,
* make use of the data returned in \p dst_buf before it returns,
* because the buffer will be overwritten unless it is the last
* call to the callback. This function will be repeatedly called
* until all gathered elements have been passed to the callback
* in \p dst_buf. The callback function should return zero (0)
* to indicate success, and a negative value to indicate failure.
*
* \since 1.10.2
*
*/
H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, size_t dst_buf_size,
void *dst_buf, H5D_gather_func_t op, void *op_data);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Closes the specified dataset
*
* \dset_id
*
* \return \herr_t
*
* \details H5Dclose() terminates access to a dataset via the identifier
* \p dset_id and releases the underlying resources.
*
* \par Example
* \snippet H5D_examples.c read
*
* \since 1.8.0
*
* \see H5Dcreate2(), H5Dopen2()
*
*/
H5_DLL herr_t H5Dclose(hid_t dset_id);
/* Internal API routines */
H5_DLL herr_t H5Ddebug(hid_t dset_id);
H5_DLL herr_t H5Dformat_convert(hid_t dset_id);
H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
* Use of these symbols is deprecated.
*/
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Macros */
#define H5D_CHUNK_BTREE H5D_CHUNK_IDX_BTREE
/* Formerly used to support the H5DOread/write_chunk() API calls.
* These symbols are no longer used in the library.
*/
/* Property names for H5DOwrite_chunk */
#define H5D_XFER_DIRECT_CHUNK_WRITE_FLAG_NAME "direct_chunk_flag"
#define H5D_XFER_DIRECT_CHUNK_WRITE_FILTERS_NAME "direct_chunk_filters"
#define H5D_XFER_DIRECT_CHUNK_WRITE_OFFSET_NAME "direct_chunk_offset"
#define H5D_XFER_DIRECT_CHUNK_WRITE_DATASIZE_NAME "direct_chunk_datasize"
/* Property names for H5DOread_chunk */
#define H5D_XFER_DIRECT_CHUNK_READ_FLAG_NAME "direct_chunk_read_flag"
#define H5D_XFER_DIRECT_CHUNK_READ_OFFSET_NAME "direct_chunk_read_offset"
#define H5D_XFER_DIRECT_CHUNK_READ_FILTERS_NAME "direct_chunk_read_filters"
/* Typedefs */
/* Function prototypes */
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Creates a dataset at the specified location
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \dcpl_id
*
* \return \hid_t{dataset}
*
* \deprecation_note{H5Dcreate2() or the macro H5Dcreate()}
*
* \details H5Dcreate1() creates a data set with a name, \p name, in the
* location specified by the identifier \p loc_id. \p loc_id may be a
* file, group, dataset, named datatype or attribute. If an attribute,
* dataset, or named datatype is specified for \p loc_id then the
* dataset will be created at the location where the attribute,
* dataset, or named datatype is attached.
*
* \p name can be a relative path based at \p loc_id or an absolute
* path from the root of the file. Use of this function requires that
* any intermediate groups specified in the path already exist.
*
* The dataset’s datatype and dataspace are specified by \p type_id and
* \p space_id, respectively. These are the datatype and dataspace of
* the dataset as it will exist in the file, which may differ from the
* datatype and dataspace in application memory.
*
* Names within a group are unique: H5Dcreate1() will return an error
* if a link with the name specified in name already exists at the
* location specified in \p loc_id.
*
* As is the case for any object in a group, the length of a dataset
* name is not limited.
*
* \p dcpl_id is an #H5P_DATASET_CREATE property list created with \p
* H5reate1() and initialized with various property list functions
* described in Property List Interface.
*
* H5Dcreate() and H5Dcreate_anon() return an error if the dataset’s
* datatype includes a variable-length (VL) datatype and the fill value
* is undefined, i.e., set to \c NULL in the dataset creation property
* list. Such a VL datatype may be directly included, indirectly
* included as part of a compound or array datatype, or indirectly
* included as part of a nested compound or array datatype.
*
* H5Dcreate() and H5Dcreate_anon() return a dataset identifier for
* success or a negative value for failure. The dataset identifier
* should eventually be closed by calling H5Dclose() to release
* resources it uses.
*
* See H5Dcreate_anon() for discussion of the differences between
* H5Dcreate() and H5Dcreate_anon().
*
* The HDF5 library provides flexible means of specifying a fill value,
* of specifying when space will be allocated for a dataset, and of
* specifying when fill values will be written to a dataset.
*
* \version 1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release.
* \since 1.0.0
*
* \see H5Dopen2(), H5Dclose(), H5Tset_size()
*
*/
H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Opens an existing dataset
*
* \fgdta_loc_id
* \param[in] name Name of the dataset to access
*
* \return \hid_t{dataset}
*
* \deprecation_note{H5Dopen2() or the macro H5Dopen()}
*
* \details H5Dopen1() opens an existing dataset for access at the location
* specified by \p loc_id. \p loc_id may be a file, group, dataset,
* named datatype or attribute. If an attribute, dataset, or named
* datatype is specified for loc_id then the dataset will be opened at
* the location where the attribute, dataset, or named datatype is
* attached. name is a dataset name and is used to identify the dataset
* in the file.
*
* A dataset opened with this function should be closed with H5Dclose()
* when the dataset is no longer needed so that resource leaks will not
* develop.
*
* \version 1.8.0 Function H5Dopen() renamed to H5Dopen1() and deprecated in this release.
* \since 1.0.0
*
*/
H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Extends a dataset
*
* \dset_id
* \param[in] size Array containing the new size of each dimension
*
* \return \herr_t
*
* \deprecation_note{H5Dset_extent()}
*
* \details H5Dextend() verifies that the dataset is at least of size \p size,
* extending it if necessary. The length of \p size is the same as
* that of the dataspace of the dataset being changed.
*
* This function can be applied to the following datasets:
* \li Any dataset with unlimited dimensions
* \li A dataset with fixed dimensions if the current dimension sizes
* are less than the maximum sizes set with \c maxdims
* (see H5Screate_simple())
*
* Space on disk is immediately allocated for the new dataset extent if
* the dataset’s space allocation time is set to
* #H5D_ALLOC_TIME_EARLY. Fill values will be written to the dataset if
* the dataset’s fill time is set to #H5D_FILL_TIME_IFSET or
* #H5D_FILL_TIME_ALLOC. (See H5Pset_fill_time() and
* H5Pset_alloc_time().)
*
* This function ensures that the dataset dimensions are of at least
* the sizes specified in size. The function H5Dset_extent() must be
* used if the dataset dimension sizes are are to be reduced.
*
* \version 1.8.0 Function deprecated in this release. Parameter size
* syntax changed to \Code{const hsize_t size[]} in this release.
*
*/
H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
*
* \brief Reclaims variable-length (VL) datatype memory buffers
*
* \type_id
* \space_id
* \dxpl_id
* \param[in] buf Pointer to the buffer to be reclaimed
*
* \return \herr_t
*
* \deprecation_note{H5Treclaim()}
*
* \details H5Dvlen_reclaim() reclaims memory buffers created to store VL
* datatypes.
*
* The \p type_id must be the datatype stored in the buffer. The \p
* space_id describes the selection for the memory buffer to free the
* VL datatypes within. The \p dxpl_id is the dataset transfer property
* list which was used for the I/O transfer to create the buffer. And
* \p buf is the pointer to the buffer to be reclaimed.
*
* The VL structures (\ref hvl_t) in the user's buffer are modified to
* zero out the VL information after the memory has been reclaimed.
*
* If nested VL datatypes were used to create the buffer, this routine
* frees them from the bottom up, releasing all the memory without
* creating memory leaks.
*
* \version 1.12.0 Function was deprecated
*
*/
H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
#ifdef __cplusplus
}
#endif
#endif /* H5Dpublic_H */
|