forked from HDFGroup/hdf5
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathH5Dpublic.h
1899 lines (1831 loc) · 77.9 KB
/
H5Dpublic.h
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
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* 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 LICENSE 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 *
* [email protected]. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
* This file contains public declarations for the H5D module.
*/
#ifndef H5Dpublic_H
#define H5Dpublic_H
#include "H5public.h" /* Generic Functions */
#include "H5Ipublic.h" /* Identifiers */
/*****************/
/* Public Macros */
/*****************/
/* Macros used to "unset" chunk cache configuration parameters */
#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT SIZE_MAX
#define H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX
#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0)
/** Bit flags for the H5Pset/get_chunk_opts() \since 1.10.0 */
#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
*
* \since 1.10.0
*
*/
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
*
* \since 1.10.2
*
*/
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.
*
* \since 1.10.2
*
*/
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.
* \return \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.
*
* \since 1.10.2
*
*/
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, taking the user block (if any) into account
* \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.
* \return \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.
*
* \callback_note
*
* \since 1.14.0
*
*/
typedef int (*H5D_chunk_iter_op_t)(const hsize_t *offset, unsigned filter_mask, haddr_t addr, hsize_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 the 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 ASYNC
* \async_variant_of{H5Dcreate}
*/
#ifndef H5_DOXYGEN
H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigned app_line, 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, hid_t es_id);
#else
H5_DLL hid_t H5Dcreate_async(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, hid_t es_id);
#endif
/**
* --------------------------------------------------------------------------
* \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 they 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 ASYNC
* \async_variant_of{H5Dopen}
*/
#ifndef H5_DOXYGEN
H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t dapl_id, hid_t es_id);
#else
H5_DLL hid_t H5Dopen_async(hid_t loc_id, const char *name, hid_t dapl_id, hid_t es_id);
#endif
/**
* --------------------------------------------------------------------------
*\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.
*
* \since 1.0.0
*
* \par Example
* \snippet H5D_examples.c update
*
* \see H5Sclose()
*
*/
H5_DLL hid_t H5Dget_space(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Dget_space}
*/
#ifndef H5_DOXYGEN
H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t es_id);
#else
H5_DLL hid_t H5Dget_space_async(hid_t dset_id, hid_t es_id);
#endif
/**
* --------------------------------------------------------------------------
* \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.
*
* \note \Bold{BUG:} Prior to the HDF5 1.14.0, 1.12.2 and 1.10.9 releases,
* H5Dget_space_status() may return incorrect space allocation status
* values for datasets with filters applied to them.
* H5Dget_space_status() calculated the space allocation status by
* comparing the sum of the sizes of all the allocated chunks in the
* dataset against the total data size of the dataset, as calculated by
* the number of elements in the dataset's dataspace multiplied by the
* dataset's datatype size. If the dataset had any compression filters
* applied to it and the dataset chunks were successfully compressed,
* the sum of the sizes of the allocated dataset chunks would generally
* always be less than the total data size of the dataset, and
* H5Dget_space_status() wouldn't ever return
* `H5D_SPACE_STATUS_ALLOCATED`.
*
* \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.
*
* \since 1.0.0
*
*/
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.
*
* \since 1.0.0
*
*/
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.
*
* \since 1.2.0
*
*/
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, taking the user block (if any) into account
* \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.
*
* \note Prior to HDF5 1.14.4, the reported address did not take the
* user block into account.
*
* \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.
*
* \note Prior to HDF5 1.14.4, the address passed to the callback did not take
* the user block into account.
*
* \par Example
* For each chunk, print the allocated chunk size (0 for unallocated chunks).
* \snippet H5D_examples.c H5Dchunk_iter_cb
* Iterate over all chunked datasets and chunks in a file.
* \snippet H5D_examples.c H5Ovisit_cb
*
* \callback_note
*
* \since 1.14.0
*
*/
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, taking the user block (if any) into account
* \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.
*
* \note Prior to HDF5 1.14.4, the reported address did not take the
* user block into account.
*
* \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 has 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 to specify 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
*
* \since 1.0.0
*
*/
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 Reads raw data from a set of datasets into the provided buffers
*
* \param[in] count Number of datasets to read from
* \param[in] dset_id Identifiers of the datasets to read from
* \param[in] mem_type_id Identifiers of the memory datatypes
* \param[in] mem_space_id Identifiers of the memory dataspaces
* \param[in] file_space_id Identifiers of the datasets' dataspaces in the file
* \param[in] dxpl_id Identifier of a transfer property list
* \param[out] buf Buffers to receive data read from file
*
* \return \herr_t
*
* \details H5Dread_multi() reads data from \p count datasets, whose identifiers
* are listed in the \p dset_id array, from the file into multiple
* application memory buffers listed in the \p buf array. Data transfer
* properties are defined by the argument \p dxpl_id. The memory
* datatypes of each dataset are listed by identifier in the \p
* mem_type_id array. The parts of each dataset to read are listed by
* identifier in the \p file_space_id array, and the parts of each
* application memory buffer to read to are listed by identifier in the
* \p mem_space_id array. All array parameters have length \p count.
*
* This function will produce the same results as \p count calls to
* H5Dread(). Information listed in that function about the specifics
* of its behavior also applies to H5Dread_multi(). By calling
* H5Dread_multi() instead of multiple calls to H5Dread(), however, the
* library can in some cases pass information about the entire I/O
* operation to the file driver, which can improve performance.
*
* All datasets must be in the same HDF5 file, and each unique dataset
* may only be listed once. If this function is called collectively in
* parallel, each rank must pass exactly the same list of datasets in
* \p dset_id , though the other parameters may differ.
*
* \since 1.14.0
*
* \see H5Dread()
*
*/
H5_DLL herr_t H5Dread_multi(size_t count, 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 ASYNC
* \async_variant_of{H5Dread}
*/
#ifndef H5_DOXYGEN
H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned app_line, 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*/, hid_t es_id);
#else
H5_DLL herr_t H5Dread_async(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*/, hid_t es_id);
#endif
/**
* --------------------------------------------------------------------------
* \ingroup ASYNC
* \async_variant_of{H5Dread_multi}
*/
#ifndef H5_DOXYGEN
H5_DLL herr_t H5Dread_multi_async(const char *app_file, const char *app_func, unsigned app_line, size_t count,
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*/, hid_t es_id);
#else
H5_DLL herr_t H5Dread_multi_async(size_t count, 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*/, hid_t es_id);
#endif
/**
* --------------------------------------------------------------------------
* \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