/
H5Lpublic.h
1595 lines (1573 loc) · 69.8 KB
/
H5Lpublic.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. *
* Copyright by the Board of Trustees of the University of Illinois. *
* 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. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*-------------------------------------------------------------------------
*
* Created: H5Lpublic.h
* Dec 1 2005
* James Laird
*
* Purpose: Public declarations for the H5L package (links)
*
*-------------------------------------------------------------------------
*/
#ifndef H5Lpublic_H
#define H5Lpublic_H
/* Public headers needed by this file */
#include "H5public.h" /* Generic Functions */
#include "H5Ipublic.h" /* IDs */
#include "H5Tpublic.h" /* Datatypes */
/*****************/
/* Public Macros */
/*****************/
/**
* \brief Maximum length of a link's name
*
* The maximum length of a link's name is encoded in a 32-bit unsigned integer.
*/
#define H5L_MAX_LINK_NAME_LEN UINT32_MAX
/**
* \brief Macro to indicate operation occurs on same location
*/
#define H5L_SAME_LOC 0 /* (hid_t) */
/**
* \brief Current version of the H5L_class_t struct
*/
#define H5L_LINK_CLASS_T_VERS 1
/**
* \brief Previous version of the H5L_class_t struct
*/
#define H5L_LINK_CLASS_T_VERS_0 0
#ifdef __cplusplus
extern "C" {
#endif
/*******************/
/* Public Typedefs */
/*******************/
/**
* \brief Link class types.
*
* Values less than 64 are reserved for the HDF5 library's internal use. Values
* 64 to 255 are for "user-defined" link class types; these types are defined
* by HDF5 but their behavior can be overridden by users. Users who want to
* create new classes of links should contact the HDF5 development team at
* mailto:help@hdfgroup.org. These values can never change because they appear
* in HDF5 files.
*/
typedef enum {
H5L_TYPE_ERROR = (-1), /**< Invalid link type id */
H5L_TYPE_HARD = 0, /**< Hard link id */
H5L_TYPE_SOFT = 1, /**< Soft link id */
H5L_TYPE_EXTERNAL = 64, /**< External link id */
H5L_TYPE_MAX = 255 /**< Maximum link type id */
} H5L_type_t;
/**
* \brief Maximum value link value for "built-in" link types
*/
#define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT
/**
* \brief Link ids at or above this value are "user-defined" link types.
*/
#define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL
/**
* \brief Information struct for links
*/
//! <!-- [H5L_info_t_snip] -->
typedef struct {
H5L_type_t type; /**< Type of link */
hbool_t corder_valid; /**< Indicate if creation order is valid */
int64_t corder; /**< Creation order */
H5T_cset_t cset; /**< Character set of link name */
union {
haddr_t address; /**< Address hard link points to */
size_t val_size; /**< Size of a soft link or user-defined link value */
} u;
} H5L_info_t;
//! <!-- [H5L_info_t_snip] -->
/* The H5L_class_t struct can be used to override the behavior of a
* "user-defined" link class. Users should populate the struct with callback
* functions defined below.
*/
/* Callback prototypes for user-defined links */
/**
* \brief Link creation callback
*/
typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata,
size_t lnkdata_size, hid_t lcpl_id);
/**
* \brief Callback for link move
*/
typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
size_t lnkdata_size);
/**
* \brief Callback for link copy
*/
typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
size_t lnkdata_size);
typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
size_t lnkdata_size, hid_t lapl_id);
/**
* \brief Callback during link traversal
*/
typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id);
/**
* \brief Callback for link deletion
*/
typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata,
size_t lnkdata_size);
/**
* \brief Callback for querying the link.
*
* Returns the size of the buffer needed.
*/
typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size,
void *buf /*out*/, size_t buf_size);
/* User-defined link types */
typedef struct {
int version; /* Version number of this struct */
H5L_type_t id; /* Link type ID */
const char * comment; /* Comment for debugging */
H5L_create_func_t create_func; /* Callback during link creation */
H5L_move_func_t move_func; /* Callback after moving link */
H5L_copy_func_t copy_func; /* Callback after copying link */
H5L_traverse_0_func_t trav_func; /* Callback during link traversal */
H5L_delete_func_t del_func; /* Callback for link deletion */
H5L_query_func_t query_func; /* Callback for queries */
} H5L_class_0_t;
/**
* \brief Link prototype
*
* The H5L_class_t struct can be used to override the behavior of a
* "user-defined" link class. Users should populate the struct with callback
* functions defined elsewhere.
*/
//! <!-- [H5L_class_t_snip] -->
typedef struct {
int version; /**< Version number of this struct */
H5L_type_t id; /**< Link type ID */
const char * comment; /**< Comment for debugging */
H5L_create_func_t create_func; /**< Callback during link creation */
H5L_move_func_t move_func; /**< Callback after moving link */
H5L_copy_func_t copy_func; /**< Callback after copying link */
H5L_traverse_func_t trav_func; /**< Callback during link traversal */
H5L_delete_func_t del_func; /**< Callback for link deletion */
H5L_query_func_t query_func; /**< Callback for queries */
} H5L_class_t;
//! <!-- [H5L_class_t_snip] -->
/**
* \brief Prototype for H5Literate(), H5Literate_by_name() operator
*/
//! <!-- [H5L_iterate_t_snip] -->
typedef herr_t (*H5L_iterate_t)(hid_t group, const char *name, const H5L_info_t *info, void *op_data);
//! <!-- [H5L_iterate_t_snip] -->
/**
* \brief Callback for external link traversal
*/
typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char *parent_group_name,
const char *child_file_name, const char *child_object_name,
unsigned *acc_flags, hid_t fapl_id, void *op_data);
/********************/
/* Public Variables */
/********************/
/*********************/
/* Public Prototypes */
/*********************/
/**
* \ingroup H5L
*
* \brief Moves a link within an HDF5 file
*
* \fgdta_loc_id{src_loc}
* \param[in] src_name Original link name
* \fgdta_loc_id{dst_loc}
* \param[in] dst_name New link name
* \lcpl_id
* \lapl_id
*
* \return \herr_t
*
* \details H5Lmove() moves a link within an HDF5 file. The original link,
* \p src_name, is removed from \p src_loc and the new link,
* \p dst_name, is inserted at dst_loc. This change is
* accomplished as an atomic operation.
*
* \p src_loc and \p src_name identify the original link.
* \p src_loc is the original location identifier; \p src_name is
* the path to the link and is interpreted relative to \p src_loc.
*
* \p dst_loc and \p dst_name identify the new link. \p dst_loc is
* either a file or group identifier; \p dst_name is the path to
* the link and is interpreted relative to \p dst_loc.
*
* \p lcpl_id and \p lapl_id are the link creation and link access
* property lists, respectively, associated with the new link,
* \p dst_name.
*
* Through these property lists, several properties are available to
* govern the behavior of H5Lmove(). The property controlling creation
* of missing intermediate groups is set in the link creation property
* list with H5Pset_create_intermediate_group(); H5Lmove() ignores any
* other properties in the link creation property list. Properties
* controlling character encoding, link traversals, and external link
* prefixes are set in the link access property list with
* H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(),
* respectively.
*
* \note Note that H5Lmove() does not modify the value of the link; the new
* link points to the same object as the original link pointed to.
* Furthermore, if the object pointed to by the original link was already
* open with a valid object identifier, that identifier will remain valid
* after the call to H5Lmove().
*
* \attention Exercise care in moving links as it is possible to render data in
* a file inaccessible with H5Lmove(). If the link being moved is on
* the only path leading to an HDF5 object, that object may become
* permanently inaccessible in the file.
*
* \since 1.8.0
*
*-------------------------------------------------------------------------
*/
H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Creates an identical copy of a link with the same creation time and
* target. The new link can have a different name and be in a different
* location than the original.
*
* \fgdt_loc_id{src_loc}
* \param[in] src_name Name of the link to be copied
* \fgdt_loc_id{dst_loc}
* \param[in] dst_name Name to be assigned to the new copy
* \lcpl_id
* \lapl_id
* \return \herr_t
*
* \details H5Lcopy() copies the link specified by \p src_name from the location
* specified by \p src_loc_id to the location specified by
* \p dst_loc_id. The new copy of the link is created with the name
* \p dst_name.
*
* If \p dst_loc_id is a file identifier, \p dst_name will be
* interpreted relative to that file’s root group.
*
* The new link is created with the creation and access property lists
* specified by \p lcpl_id and \p lapl_id. The interpretation of
* \p lcpl_id is limited in the manner described in the next paragraph.
*
* H5Lcopy() retains the creation time and the target of the original
* link. However, since the link may be renamed, the character
* encoding is that specified in \p lcpl_id rather than that of the
* original link. Other link creation properties are ignored.
*
* If the link is a soft link, also known as a symbolic link, its
* target is interpreted relative to the location of the copy.
*
* Several properties are available to govern the behavior of
* H5Lcopy(). These properties are set in the link creation and access
* property lists, \p lcpl_id and \p lapl_id, respectively. The
* property controlling creation of missing intermediate groups is set
* in the link creation property list with
* H5Pset_create_intermediate_group(); this function ignores any
* other properties in the link creation property list. Properties
* controlling character encoding, link traversals, and external link
* prefixes are set in the link access property list with
* H5Pset_char_encoding(), H5Pset_nlinks(), and
* H5Pset_elink_prefix().
*
* \note H5Lcopy() does not affect the object that the link points to.
*
* \attention H5Lcopy() cannot copy hard links across files as a hard link is
* not valid without a target object; to copy objects from one file
* to another, see H5Ocopy().
*
* \see H5Ocopy()
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Creates a hard link to an object
*
* \fgdta_loc_id{cur_loc}
* \param[in] cur_name Name of the target object, which must already exist
* \fgdta_loc_id{dst_loc}
* \param[in] dst_name The name of the new link
* \lcpl_id
* \lapl_id
*
* \return \herr_t
*
* \details H5Lcreate_hard() creates a new hard link to a pre-existing object
* in an HDF5 file.
*
* \p cur_loc and \p cur_name specify the location
* and name, respectively, of the target object, i.e., the object that
* the new hard link points to. \p dst_loc and \p dst_name specify the
* location and name, respectively, of the new hard link.
*
* \p cur_name and \p dst_name are interpreted relative to \p cur_loc
* and \p dst_loc, respectively. If \p cur_loc and \p dst_loc are the
* same location, the HDF5 macro #H5L_SAME_LOC can be used for either
* parameter (but not both).
*
* \p lcpl_id and \p lapl_id are the link creation and access property
* lists associated with the new link.
*
* \note Hard and soft links are for use only if the target object is in the
* current file. If the desired target object is in a different file from
* the new link, an external link may be created with
* H5Lcreate_external().
*
* \note The HDF5 library keeps a count of all hard links pointing to an
* object; if the hard link count reaches zero (0), the object will be
* deleted from the file. Creating new hard links to an object will
* prevent it from being deleted if other links are removed. The
* library maintains no similar count for soft links and they can dangle.
*
* \note The new link may be one of many that point to that object.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name,
hid_t lcpl_id, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Creates a soft link
*
* \param[in] link_target An HDF5 path name
* \fgdta_loc_id{link_loc_id}
* \param[in] link_name The name of the new link
* \lcpl_id
* \lapl_id
*
* \return \herr_t
*
* \details H5Lcreate_soft() creates a new soft link to an object in an HDF5
* file.
*
* \p link_target specifies the HDF5 path name the soft link contains.
* \p link_target can be an arbitrary HDF5 path name and is
* interpreted only at lookup time. This path may be absolute in the
* file or relative to \p link_loc_id.
*
* \p link_loc_id and \p link_name specify the location and name,
* respectively, of the new soft link. \p link_name is interpreted
* relative to \p link_loc_id and must contain only the name of the soft
* link; \p link_name may not contain any additional path elements.
*
* If \p link_loc_id is a group identifier, the object pointed to by
* \p link_name will be accessed as a member of that group. If
* \p link_loc_id is a file identifier, the object will be accessed as a
* member of the file's root group.
*
* \p lcpl_id and \p lapl_id are the link creation and access property
* lists associated with the new link.
*
* For instance, if target_path is \c ./foo, \p link_loc_id specifies
* \c ./x/y/bar, and the name of the new link is \c new_link, then a
* subsequent request for \c ./x/y/bar/new_link will return same the
* object as would be found at \c ./foo.
*
* \note H5Lcreate_soft() is for use only if the target object is in the
* current file. If the desired target object is in a different file from
* the new link, use H5Lcreate_external() to create an external link.
*
* \note Soft links and external links are also known as symbolic links as they
* use a name to point to an object; hard links employ an object’s
* address in the file.
*
* \note Unlike hard links, a soft link in an HDF5 file is allowed to dangle,
* meaning that the target object need not exist at the time that the
* link is created.
*
* \note The HDF5 library does not keep a count of soft links as it does of
* hard links.
*
* \note The new link may be one of many that point to that object.
*
* \see H5Lcreate_hard(), H5Lcreate_external()
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id,
hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Removes a link from a group
*
* \fgdta_loc_id
* \param[in] name Name of the link to delete
* \lapl_id
*
* \return \herr_t
*
* \details H5Ldelete() removes the link specified by \p name from the location
* \p loc_id.
*
* If the link being removed is a hard link, H5Ldelete() also
* decrements the link count for the object to which name points.
* Unless there is a duplicate hard link in that group, this action
* removes the object to which name points from the group that
* previously contained it.
*
* Object headers keep track of how many hard links refer to an
* object; when the hard link count, also referred to as the reference
* count, reaches zero, the object can be removed from the file. The
* file space associated will then be released, i.e., identified in
* memory as freespace. Objects which are open are not removed until
* all identifiers to the object are closed.
*
* \attention Exercise caution in the use of H5Ldelete(); if the link being
* removed is on the only path leading to an HDF5 object, that
* object may become permanently inaccessible in the file.
*
* \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_external()
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Removes the \Emph{n}-th link in a group
*
* \fgdta_loc_id
* \param[in] group_name Name of subject group
* \param[in] idx_type Index or field which determines the order
* \param[in] order Order within field or index
* \param[in] n Link for which to retrieve information
* \lapl_id
*
* \return \herr_t
*
* \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group
* according to the specified order, \p order, in the specified index,
* \p index.
*
* If \p loc_id specifies the group in which the link resides,
* \p group_name can be a dot (\c .).
*
* \see H5Ldelete()
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Returns the value of a link
*
* \fgdta_loc_id
* \param[in] name Link name
* \param[out] buf The buffer to hold the link value
* \param[in] size Maximum number of bytes of link value to be returned
* \lapl_id
*
* \return \herr_t
*
* \details H5Lget_val() returns the value of link \p name. For smbolic links,
* this is the path to which the link points, including the null
* terminator. For external and user-defined links, it is the link
* buffer.
*
* \p size is the size of \p buf and should be the size of the link
* value being returned. This size value can be determined through a
* call to H5Lget_info(); it is returned in the \c val_size field of
* the \ref H5L_info_t \c struct.
*
* If \p size is smaller than the size of the returned value, then the
* string stored in \p buf will be truncated to \p size bytes. For
* soft links, this means that the value will not be null terminated.
*
* In the case of external links, the target file and object names are
* extracted from \p buf by calling H5Lunpack_elink_val().
*
* The link class of link \p name can be determined with a call to
* H5Lget_info().
*
* \p lapl_id specifies the link access property list associated with
* the link \p name. In the general case, when default link access
* properties are acceptable, this can be passed in as #H5P_DEFAULT. An
* example of a situation that requires a non-default link access
* property list is when the link is an external link; an external
* link may require that a link prefix be set in a link access
* property list (see H5Pset_elink_prefix()).
*
* This function should be used only after H5Lget_info() has been
* called to verify that \p name is a symbolic link. This can be
* determined from the \c link_type field of the \ref H5L_info_t
* \c struct.
*
* \note This function will fail if called on a hard link.
*
* \see H5Lget_val_by_idx()
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size_t size, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Retrieves value of the \Emph{n}-th link in a group, according to the order within an index
*
* \fgdta_loc_id
* \param[in] group_name Group name
* \param[in] idx_type Type of index
* \param[in] order Order within field or index
* \param[in] n Link position for which to retrieve information
* \param[out] buf The buffer to hold the link value
* \param[in] size Maximum number of bytes of link value to be returned
* \lapl_id
*
* \return \herr_t
*
* \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in
* a group, according to the specified order, \p order, within an
* index, \p index.
*
* For soft links, the value is an HDF5 path name.
*
* For external links, this is a compound value containing file and
* path name information; to use this external link information, it
* must first be decoded with H5Lunpack_elink_val()
*
* For user-defined links, this value will be described in the
* definition of the user-defined link type.
*
* \p loc_id specifies the location identifier of the group specified
* by \p group_name.
*
* \p group_name specifies the group in which the link exists. If
* \p loc_id already specifies the group in which the link exists,
* \p group_name must be a dot (\c .).
*
* The size in bytes of link_val is specified in \p size. The size
* value can be determined through a call to H5Lget_info_by_idx(); it
* is returned in the \c val_size field of the \ref H5L_info_t
* \c struct. If
* size is smaller than the size of the returned value, then the
* string stored in link_val will be truncated to size bytes. For soft
* links, this means that the value will not be null terminated.
*
* If the type of the link is unknown or uncertain, H5Lget_val_by_idx()
* should be called only after the type has been determined via a call
* to H5Lget_info_by_idx().
*
* \note This function will fail if called on a hard link.
*
* \see H5Lget_val()
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, void *buf /*out*/, size_t size,
hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Determines whether a link with the specified name exists in a group
*
* \fgdta_loc_id
* \param[in] name Link name
* \lapl_id
*
* \return \herr_t
*
* \details H5Lexists() allows an application to determine whether the link \p
* name exists in the location specified by \p loc_id. The link may be
* of any type; only the presence of a link with that name is checked.
*
* Note that H5Lexists() verifies only that the target link exists. If
* name includes either a relative path or an absolute path to the
* target link, intermediate steps along the path must be verified
* before the existence of the target link can be safely checked. If
* the path is not verified, and an intermediate element of the path
* does not exist, H5Lexists() will fail. The example in the next
* paragraph illustrates one step-by-step method for verifying the
* existence of a link with a relative or absolute path.
*
* \Bold{Example:} Use the following steps to verify the existence of
* the link \c datasetD in the \c group group1/group2/softlink_to_group3/,
* where \c group1 is a member of the group specified by \c loc_id:
*
* 1. First use H5Lexists() to verify that \c group1 exists.
* 2. If \c group1 exists, use H5Lexists() again, this time with name
* set to \c group1/group2, to verify that \c group2 exists.
* 3. If \c group2 exists, use H5Lexists() with name set to
* \c group1/group2/softlink_to_group3 to verify that
* \c softlink_to_group3 exists.
* 4. If \c softlink_to_group3 exists, you can now safely use
* H5Lexists() with \c name set to
* \c group1/group2/softlink_to_group3/datasetD to verify that the
* target link, \c datasetD, exists.
*
* If the link to be verified is specified with an absolute path, the
* same approach should be used, but starting with the first link in
* the file’s root group. For instance, if \c datasetD were in
* \c /group1/group2/softlink_to_group3, the first call to H5Lexists()
* would have name set to \c /group1.
*
* Note that this is an outline and does not include all necessary
* details. Depending on circumstances, for example, you may need to
* verify that an intermediate link points to a group and that a soft
* link points to an existing target.
*
* \note The behavior of H5Lexists() was changed in the 1.10 release in the
* case where the root group, \c "/", is the name of the link. This
* change is described below:
* <ol>
* <li>Let \c file denote a valid HDF5 file identifier, and let \c lapl
* denote a valid link access property list identifier. A call to
* H5Lexists() with arguments \c file, \c "/", and \c lapl
* returns a positive value; in other words,
* \Code{H5Lexists(file, "/", lapl)} returns a positive value.
* In HDF5 version 1.8.16, this function returns 0.</li>
* <li>Let \c root denote a valid HDF5 group identifier that refers to the
* root group of an HDF5 file, and let \c lapl denote a valid link
* access property list identifier. A call to H5Lexists() with
* arguments c root, \c "/", and \c lapl returns a positive value;
* in other words, \Code{H5Lexists(root, "/", lapl)} returns a positive
* value. In HDF5 version 1.8.16, this function returns 0.</li>
* </ol>
* Note that the function accepts link names and path names. This is
* potentially misleading to callers, and we plan to separate the
* functionality for link names and path names in a future release.
*
* \attention H5Lexists() checks the existence of only the final element in a
* relative or absolute path; it does not check any other path
* elements. The function will therefore fail when both of the
* following conditions exist:
* - \c name is not local to the group specified by \c loc_id or,
* if \c loc_id is something other than a group identifier, \c name
* is not local to the root group.
* - Any element of the relative path or absolute path in name,
* except the target link, does not exist.
*
* \version 1.10.0 Function behavior changed in this release. (See the note.)
* \since 1.8.0
*
*/
H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Returns information about a link
*
* \fgdta_loc_id
* \param[in] name Link name
* \param[out] linfo Buffer in which link information is returned
* \lapl_id
*
* \return \herr_t
*
* \details H5Lget_info() returns information about the specified link through
* the \p linfo argument.
*
* The location identifier, \p loc_id, specifies the location of the
* link. A link name, \p name, interpreted relative to \p loc_id,
* specifies the link being queried.
*
* \p lapl_id is the link access property list associated with the
* link name. In the general case, when default link access properties
* are acceptable, this can be passed in as #H5P_DEFAULT. An example
* of a situation that requires a non-default link access property
* list is when the link is an external link; an external link may
* require that a link prefix be set in a link access property list
* (see H5Pset_elink_prefix()).
*
* H5Lget_info() returns information about name in the data structure
* H5L_info_t, which is described below and defined in H5Lpublic.h.
* This structure is returned in the buffer \p linfo.
* \snippet this H5L_info_t_snip
* In the above struct, \c type specifies the link class. Valid values
* include the following:
* \link_types
* There will be additional valid values if user-defined links have
* been registered.
*
* \p corder specifies the link’s creation order position while
* \p corder_valid indicates whether the value in corder is valid.
*
* If \p corder_valid is \c TRUE, the value in \p corder is known to
* be valid; if \p corder_valid is \c FALSE, the value in \p corder is
* presumed to be invalid; \p corder starts at zero (0) and is
* incremented by one (1) as new links are created. But
* higher-numbered entries are not adjusted when a lower-numbered link
* is deleted; the deleted link's creation order position is simply
* left vacant. In such situations, the value of \p corder for the
* last link created will be larger than the number of links remaining
* in the group.
*
* \p cset specifies the character set in which the link name is
* encoded. Valid values include the following:
* \csets
* This value is set with H5Pset_char_encoding().
*
* \c address and \c val_size are returned for hard and symbolic
* links, respectively. Symbolic links include soft and external links
* and some user-defined links.
*
* If the link is a hard link, \c address specifies the file address
* that the link points to.
*
* If the link is a symbolic link, \c val_size will be the length of
* the link value, e.g., the length of the HDF5 path name with a null
* terminator.
*
* \version 1.8.2 Fortran subroutine added in this release.
* \version 1.8.4 Fortran subroutine syntax changed in this release.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Retrieves metadata for a link in a group, according to the order
* within a field or index
*
* \loc_id
* \param[in] group_name Group name
* \idx_type
* \order
* \param[in] n Link position for which to retrieve information
* \param[out] linfo Buffer in which link information is returned
* \lapl_id
*
* \return \herr_t
*
* \details H5get_info_by_idx() returns the metadata for a link in a group
* according to a specified field or index and a specified order. The
* link for which information is to be returned is specified by \p
* idx_type, \p order, and \p n as follows:
*
* - \p idx_type specifies the field by which the links in \p
* group_name are ordered. The links may be indexed on this field,
* in which case operations seeking specific links are likely to
* complete more quickly.
* - \p order specifies the order in which
* the links are to be referenced for the purposes of this function.
* - \p n specifies the position of the subject link. Note that this
* count is zero-based; 0 (zero) indicates that the function will
* return the value of the first link; if \p n is 5, the function
* will return the value of the sixth link; etc.
*
* For example, assume that \p idx_type, \p order, and \p n are
* #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME
* indicates that the links are accessed in lexicographic order by
* their names. #H5_ITER_DEC specifies that the list be traversed in
* reverse order, or in decremented order. And 5 specifies that this
* call to the function will return the metadata for the 6th link
* (\c n + 1) from the end.
*
* See H5Literate() for a list of valid values and further discussion
* regarding \p idx_type and \p order.
*
* If \p loc_id specifies the group in which the link resides,
* \p group_name can be a dot (\c .).
*
* \version 1.8.4 Fortran subroutine syntax changed in this release.
* \version 1.8.2 Fortran subroutine added in this release.
*
* \since 1.8.0
*
*/
H5_DLL herr_t H5Lget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, H5L_info_t *linfo, hid_t lapl_id);
/**
* \ingroup H5L
*
* \brief Retrieves name of the \Emph{n}-th link in a group, according to the
* order within a specified field or index
*
* \loc_id
* \param[in] group_name Group name
* \idx_type
* \order
* \param[in] n Link position for which to retrieve information
* \param[out] name Buffer in which link name is returned
* \param[in] size Size in bytes of \p name
* \lapl_id
*
* \return Returns the size of the link name if successful; otherwise returns a
* negative value.
*
* \details H5get_name_by_idx() retrieves the name of the \Emph{n}-th link in a
* group, according to the specified order, \p order, within a specified
* field or index, \p idx_type.
*
* \p idx_type specifies the index that is used. Valid values include
* the following:
* \indexes
*
* \p order specifies the order in which objects are inspected along
* the index specified in \p idx_type. Valid values include the
* following:
* \orders
*
* If \p loc_id specifies the group in which the link resides,
* \p group_name can be a dot (\c .).
*
* The size in bytes of name is specified in \p size. If \p size is
* unknown, it can be determined via an initial H5Lget_name_by_idx()
* call with name set to NULL; the function's return value will be the
* size of the name.
*
* \note Please note that in order for the specified index to correspond to the
* creation order index, \p order must be set to #H5_ITER_INC or
* #H5_ITER_DEC when calling H5Lget_name_by_idx(). \note The index \p n
* passed to H5Lget_name_by_idx() is the index of the link within the
* link table, sorted according to \p order and \p idx_type. If order is
* #H5_ITER_NATIVE, then the link table is not sorted, and it does not
* matter what \p idx_type is. Specifying #H5_ITER_NATIVE does not
* guarantee any particular order, only that it remains consistent.
*
* \since 1.8.0
*
*/
H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size,
hid_t lapl_id);
/**
* \ingroup TRAV
*
* \brief Iterates over links in a group, with user callback routine,
* according to the order within an index.
*
* \group_id{grp_id}
* \idx_type
* \order
* \param[in,out] idx Pointer to an iteration index to allow
* continuing a previous iteration
* \op
* \op_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 H5Literate() iterates through the links in a file or
* group, \p group_id, in the order of the specified
* index, \p idx_type, using a user-defined callback routine
* \p op. H5Literate() does not recursively follow links into
* subgroups of the specified group.
*
* Three parameters are used to manage progress of the iteration:
* \p idx_type, \p order, and \p idx_p.
*
* \p idx_type specifies the index to be used. If the links have
* not been indexed by the index type, they will first be sorted by
* that index then the iteration will begin; if the links have been
* so indexed, the sorting step will be unnecessary, so the iteration
* may begin more quickly.
*
* \p order specifies the order in which objects are to be inspected
* along the index \p idx_type.
*
* \p idx_p tracks the iteration and allows an iteration to be
* resumed if it was stopped before all members were processed. It is
* passed in by the application with a starting point and returned by
* the library with the point at which the iteration stopped.
*
* \p op_data is a user-defined pointer to the data required to
* process links in the course of the iteration. This pointer is
* passed back to each step of the iteration in the \p op callback
* function's \p op_data parameter. \p op is invoked for each link
* encounter.
*
* \p op_data is passed to and from each iteration and can be used to
* supply or aggregate information across iterations.
*
* \remark Same pattern of behavior as H5Giterate().
*
* \note This function is also available through the H5Literate() macro.
*
* \warning The behavior of H5Literate() is undefined if the link
* membership of \p group_id changes during the iteration.
* This does not limit the ability to change link destinations
* while iterating, but caution is advised.
*
*
* \since 1.8.0
*
* \see H5Literate_by_name(), H5Lvisit(), H5Lvisit_by_name()
*
*/
H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
H5L_iterate_t op, void *op_data);
/**
* \ingroup TRAV
*
* \brief Iterates through links in a group
*
* \loc_id
* \param[in] group_name Group name
* \idx_type
* \order
* \param[in,out] idx iteration position at which to start (\Emph{IN}) or
* position at which an interrupted iteration may be restarted
* (\Emph{OUT})
* \op
* \op_data
* \lapl_id
* \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 H5Literate_by_name() iterates through the links in a group
* specified by \p loc_id and \p group_name, in the order of the
* specified index, \p idx_type, using a user-defined callback routine
* \p op. H5Literate_by_name() does not recursively follow links into
* subgroups of the specified group.
*
* \p idx_type specifies the index to be used. If the links have not
* been indexed by the index type, they will first be sorted by that
* index then the iteration will begin; if the links have been so
* indexed, the sorting step will be unnecessary, so the iteration may
* begin more quickly. Valid values include the following:
* \indexes
*
* \p order specifies the order in which objects are to be inspected
* along the index specified in \p idx_type. Valid values include the
* following:
* \orders
*
* \p idx allows an interrupted iteration to be resumed; it is
* passed in by the application with a starting point and returned by
* the library with the point at which the iteration stopped.
*
* \note H5Literate_by_name() is not recursive. In particular, if a member of
* \p group_name is found to be a group, call it \c subgroup_a,
* H5Literate_by_name() does not examine the members of \c subgroup_a.
* When recursive iteration is required, the application must handle the
* recursion, explicitly calling H5Literate_by_name1() on discovered
* subgroups.
*
* \note H5Literate_by_name() assumes that the membership of the group being
* iterated over remains unchanged through the iteration; if any of the
* links in the group change during the iteration, the function’s
* behavior is undefined. Note, however, that objects pointed to by the
* links can be modified.
*