HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
H5Opublic.h
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2  * Copyright by The HDF Group. *
3  * Copyright by the Board of Trustees of the University of Illinois. *
4  * All rights reserved. *
5  * *
6  * This file is part of HDF5. The full HDF5 copyright notice, including *
7  * terms governing use, modification, and redistribution, is contained in *
8  * the files COPYING and Copyright.html. COPYING can be found at the root *
9  * of the source code distribution tree; Copyright.html can be found at the *
10  * root level of an installed copy of the electronic HDF5 document set and *
11  * is linked from the top-level documents page. It can also be found at *
12  * http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
13  * access to either file, you may request a copy from help@hdfgroup.org. *
14  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /*-------------------------------------------------------------------------
17  *
18  * Created: H5Opublic.h
19  * Aug 5 1997
20  * Robb Matzke <matzke@llnl.gov>
21  *
22  * Purpose: Public declarations for the H5O (object header)
23  * package.
24  *
25  *-------------------------------------------------------------------------
26  */
27 #ifndef _H5Opublic_H
28 #define _H5Opublic_H
29 
30 /* Public headers needed by this file */
31 #include "H5public.h" /* Generic Functions */
32 #include "H5Ipublic.h" /* IDs */
33 #include "H5Lpublic.h" /* Links */
34 
35 /*****************/
36 /* Public Macros */
37 /*****************/
38 
39 /* Flags for object copy (H5Ocopy) */
40 #define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */
41 #define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */
42 #define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */
43 #define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */
44 #define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */
45 #define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */
46 #define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */
47 #define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */
48 
49 /* Flags for shared message indexes.
50  * Pass these flags in using the mesg_type_flags parameter in
51  * H5P_set_shared_mesg_index.
52  * (Developers: These flags correspond to object header message type IDs,
53  * but we need to assign each kind of message to a different bit so that
54  * one index can hold multiple types.)
55  */
56 #define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */
57 #define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */
58 #define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */
59 #define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */
60 #define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */
61 #define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */
62 #define H5O_SHMESG_ALL_FLAG (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | H5O_SHMESG_ATTR_FLAG)
63 
64 /* Object header status flag definitions */
65 #define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */
66 #define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */
67 #define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */
68 #define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */
69 #define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */
70 #define H5O_HDR_ALL_FLAGS (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES)
71 
72 /* Maximum shared message values. Number of indexes is 8 to allow room to add
73  * new types of messages.
74  */
75 #define H5O_SHMESG_MAX_NINDEXES 8
76 #define H5O_SHMESG_MAX_LIST_SIZE 5000
77 
78 /*******************/
79 /* Public Typedefs */
80 /*******************/
81 
82 /* Types of objects in file */
83 typedef enum H5O_type_t {
84  H5O_TYPE_UNKNOWN = -1, /* Unknown object type */
85  H5O_TYPE_GROUP, /* Object is a group */
86  H5O_TYPE_DATASET, /* Object is a dataset */
87  H5O_TYPE_NAMED_DATATYPE, /* Object is a named data type */
88  H5O_TYPE_NTYPES /* Number of different object types (must be last!) */
89 } H5O_type_t;
90 
91 /* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */
92 typedef struct H5O_hdr_info_t {
93  unsigned version; /* Version number of header format in file */
94  unsigned nmesgs; /* Number of object header messages */
95  unsigned nchunks; /* Number of object header chunks */
96  unsigned flags; /* Object header status flags */
97  struct {
98  hsize_t total; /* Total space for storing object header in file */
99  hsize_t meta; /* Space within header for object header metadata information */
100  hsize_t mesg; /* Space within header for actual message information */
101  hsize_t free; /* Free space within object header */
102  } space;
103  struct {
104  uint64_t present; /* Flags to indicate presence of message type in header */
105  uint64_t shared; /* Flags to indicate message type is shared in header */
106  } mesg;
108 
109 /* Information struct for object (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */
110 typedef struct H5O_info_t {
111  unsigned long fileno; /* File number that object is located in */
112  haddr_t addr; /* Object address in file */
113  H5O_type_t type; /* Basic object type (group, dataset, etc.) */
114  unsigned rc; /* Reference count of object */
115  time_t atime; /* Access time */
116  time_t mtime; /* Modification time */
117  time_t ctime; /* Change time */
118  time_t btime; /* Birth time */
119  hsize_t num_attrs; /* # of attributes attached to object */
120  H5O_hdr_info_t hdr; /* Object header information */
121  /* Extra metadata storage for obj & attributes */
122  struct {
123  H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
124  H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
125  } meta_size;
126 } H5O_info_t;
127 
128 /* Typedef for message creation indexes */
129 typedef uint32_t H5O_msg_crt_idx_t;
130 
131 /* Prototype for H5Ovisit/H5Ovisit_by_name() operator */
132 typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info,
133  void *op_data);
134 
135 typedef enum H5O_mcdt_search_ret_t {
136  H5O_MCDT_SEARCH_ERROR = -1, /* Abort H5Ocopy */
137  H5O_MCDT_SEARCH_CONT, /* Continue the global search of all committed datatypes in the destination file */
138  H5O_MCDT_SEARCH_STOP /* Stop the search, but continue copying. The committed datatype will be copied but not merged. */
140 
141 /* Callback to invoke when completing the search for a matching committed datatype from the committed dtype list */
142 typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data);
143 
144 /********************/
145 /* Public Variables */
146 /********************/
147 
148 
149 #ifdef __cplusplus
150 extern "C" {
151 #endif
152 
153 /*********************/
154 /* Public Prototypes */
155 /*********************/
156 H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id);
158 H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name,
159  H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id);
160 H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
161 H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo);
162 H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oinfo,
163  hid_t lapl_id);
164 H5_DLL herr_t H5Oget_info_by_idx(hid_t loc_id, const char *group_name,
165  H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info_t *oinfo,
166  hid_t lapl_id);
167 H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name,
168  hid_t lcpl_id, hid_t lapl_id);
171 H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id,
172  const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id);
173 H5_DLL herr_t H5Oset_comment(hid_t obj_id, const char *comment);
174 H5_DLL herr_t H5Oset_comment_by_name(hid_t loc_id, const char *name,
175  const char *comment, hid_t lapl_id);
176 H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize);
177 H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name,
178  char *comment, size_t bufsize, hid_t lapl_id);
179 H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order,
180  H5O_iterate_t op, void *op_data);
181 H5_DLL herr_t H5Ovisit_by_name(hid_t loc_id, const char *obj_name,
182  H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op,
183  void *op_data, hid_t lapl_id);
184 H5_DLL herr_t H5Oclose(hid_t object_id);
185 
186 /* Symbols defined for compatibility with previous versions of the HDF5 API.
187  *
188  * Use of these symbols is deprecated.
189  */
190 #ifndef H5_NO_DEPRECATED_SYMBOLS
191 
192 /* Macros */
193 
194 /* Typedefs */
195 
196 /* A struct that's part of the H5G_stat_t routine (deprecated) */
197 typedef struct H5O_stat_t {
198  hsize_t size; /* Total size of object header in file */
199  hsize_t free; /* Free space within object header */
200  unsigned nmesgs; /* Number of object header messages */
201  unsigned nchunks; /* Number of object header chunks */
202 } H5O_stat_t;
203 
204 /* Function prototypes */
205 
206 #endif /* H5_NO_DEPRECATED_SYMBOLS */
207 
208 #ifdef __cplusplus
209 }
210 #endif
211 #endif /* _H5Opublic_H */
212 
GLenum GLuint GLsizei bufsize
Definition: glcorearb.h:1817
H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id)
H5_DLL herr_t H5Oset_comment_by_name(hid_t loc_id, const char *name, const char *comment, hid_t lapl_id)
H5_DLL hid_t H5Oopen_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)
H5_index_t
Definition: H5public.h:289
unsigned version
Definition: H5Opublic.h:93
hsize_t num_attrs
Definition: H5Opublic.h:119
H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oinfo, hid_t lapl_id)
#define H5_DLL
Definition: H5api_adpt.h:406
time_t btime
Definition: H5Opublic.h:118
haddr_t addr
Definition: H5Opublic.h:112
H5_DLL herr_t H5Oget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info_t *oinfo, hid_t lapl_id)
H5_DLL herr_t H5Odecr_refcount(hid_t object_id)
int herr_t
Definition: H5public.h:107
H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id)
herr_t(* H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data)
Definition: H5Opublic.h:132
unsigned long long hsize_t
Definition: H5public.h:151
unsigned rc
Definition: H5Opublic.h:114
H5_DLL herr_t H5Oclose(hid_t object_id)
unsigned nchunks
Definition: H5Opublic.h:95
H5O_type_t
Definition: H5Opublic.h:83
H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize)
struct H5O_stat_t H5O_stat_t
unsigned nmesgs
Definition: H5Opublic.h:200
hsize_t free
Definition: H5Opublic.h:101
H5O_mcdt_search_ret_t(* H5O_mcdt_search_cb_t)(void *op_data)
Definition: H5Opublic.h:142
GLdouble n
Definition: glcorearb.h:2007
hsize_t meta
Definition: H5Opublic.h:99
uint64_t haddr_t
Definition: H5public.h:163
unsigned nchunks
Definition: H5Opublic.h:201
H5_DLL herr_t H5Oincr_refcount(hid_t object_id)
unsigned nmesgs
Definition: H5Opublic.h:94
hsize_t free
Definition: H5Opublic.h:199
H5_iter_order_t
Definition: H5public.h:268
time_t mtime
Definition: H5Opublic.h:116
hsize_t size
Definition: H5Opublic.h:198
H5_DLL herr_t H5Ovisit(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data)
struct H5O_hdr_info_t::@67 space
int hid_t
Definition: H5Ipublic.h:56
H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id)
GLuint const GLchar * name
Definition: glcorearb.h:785
time_t ctime
Definition: H5Opublic.h:117
unsigned flags
Definition: H5Opublic.h:96
time_t atime
Definition: H5Opublic.h:115
uint64_t shared
Definition: H5Opublic.h:105
H5O_mcdt_search_ret_t
Definition: H5Opublic.h:135
H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo)
H5_DLL herr_t H5Ovisit_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op, void *op_data, hid_t lapl_id)
uint32_t H5O_msg_crt_idx_t
Definition: H5Opublic.h:129
H5O_hdr_info_t hdr
Definition: H5Opublic.h:120
H5_ih_info_t obj
Definition: H5Opublic.h:123
hsize_t mesg
Definition: H5Opublic.h:100
H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comment, size_t bufsize, hid_t lapl_id)
unsigned long fileno
Definition: H5Opublic.h:111
H5O_type_t type
Definition: H5Opublic.h:113
hsize_t total
Definition: H5Opublic.h:98
H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr)
H5_ih_info_t attr
Definition: H5Opublic.h:124
H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id)
H5_DLL herr_t H5Oset_comment(hid_t obj_id, const char *comment)
uint64_t present
Definition: H5Opublic.h:104
struct H5O_hdr_info_t H5O_hdr_info_t
int htri_t
Definition: H5public.h:126
struct H5O_info_t H5O_info_t
struct H5O_info_t::@69 meta_size