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 COPYING file, which can be found at the root of the source code * 9 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * 10 * If you do not have access to either file, you may request a copy from * 11 * help@hdfgroup.org. * 12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 13 14 /* 15 * This file contains public declarations for the H5F module. 16 */ 17 #ifndef _H5Fpublic_H 18 #define _H5Fpublic_H 19 20 /* Public header files needed by this file */ 21 #include "H5public.h" 22 #include "H5ACpublic.h" 23 #include "H5Ipublic.h" 24 25 /* When this header is included from a private header, don't make calls to H5check() */ 26 #undef H5CHECK 27 #ifndef _H5private_H 28 #define H5CHECK H5check(), 29 #else /* _H5private_H */ 30 #define H5CHECK 31 #endif /* _H5private_H */ 32 33 /* When this header is included from a private HDF5 header, don't make calls to H5open() */ 34 #undef H5OPEN 35 #ifndef _H5private_H 36 #define H5OPEN H5open(), 37 #else /* _H5private_H */ 38 #define H5OPEN 39 #endif /* _H5private_H */ 40 41 /* 42 * These are the bits that can be passed to the `flags' argument of 43 * H5Fcreate() and H5Fopen(). Use the bit-wise OR operator (|) to combine 44 * them as needed. As a side effect, they call H5check_version() to make sure 45 * that the application is compiled with a version of the hdf5 header files 46 * which are compatible with the library to which the application is linked. 47 * We're assuming that these constants are used rather early in the hdf5 48 * session. 49 */ 50 #define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /*absence of rdwr => rd-only */ 51 #define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /*open for read and write */ 52 #define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /*overwrite existing files */ 53 #define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /*fail if file already exists*/ 54 /* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */ 55 #define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /*create non-existing files */ 56 #define H5F_ACC_SWMR_WRITE (H5CHECK 0x0020u) /*indicate that this file is 57 * open for writing in a 58 * single-writer/multi-reader (SWMR) 59 * scenario. Note that the 60 * process(es) opening the file 61 * for reading must open the file 62 * with RDONLY access, and use 63 * the special "SWMR_READ" access 64 * flag. */ 65 #define H5F_ACC_SWMR_READ (H5CHECK 0x0040u) /*indicate that this file is 66 * open for reading in a 67 * single-writer/multi-reader (SWMR) 68 * scenario. Note that the 69 * process(es) opening the file 70 * for SWMR reading must also 71 * open the file with the RDONLY 72 * flag. */ 73 74 /* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the 75 * parent file. */ 76 #define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /*ignore setting on lapl */ 77 78 /* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */ 79 #define H5F_OBJ_FILE (0x0001u) /* File objects */ 80 #define H5F_OBJ_DATASET (0x0002u) /* Dataset objects */ 81 #define H5F_OBJ_GROUP (0x0004u) /* Group objects */ 82 #define H5F_OBJ_DATATYPE (0x0008u) /* Named datatype objects */ 83 #define H5F_OBJ_ATTR (0x0010u) /* Attribute objects */ 84 #define H5F_OBJ_ALL (H5F_OBJ_FILE|H5F_OBJ_DATASET|H5F_OBJ_GROUP|H5F_OBJ_DATATYPE|H5F_OBJ_ATTR) 85 #define H5F_OBJ_LOCAL (0x0020u) /* Restrict search to objects opened through current file ID */ 86 /* (as opposed to objects opened through any file ID accessing this file) */ 87 88 #define H5F_FAMILY_DEFAULT (hsize_t)0 89 90 #ifdef H5_HAVE_PARALLEL 91 /* 92 * Use this constant string as the MPI_Info key to set H5Fmpio debug flags. 93 * To turn on H5Fmpio debug flags, set the MPI_Info value with this key to 94 * have the value of a string consisting of the characters that turn on the 95 * desired flags. 96 */ 97 #define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key" 98 #endif /* H5_HAVE_PARALLEL */ 99 100 /* The difference between a single file and a set of mounted files */ 101 typedef enum H5F_scope_t { 102 H5F_SCOPE_LOCAL = 0, /*specified file handle only */ 103 H5F_SCOPE_GLOBAL = 1 /*entire virtual file */ 104 } H5F_scope_t; 105 106 /* Unlimited file size for H5Pset_external() */ 107 #define H5F_UNLIMITED ((hsize_t)(-1L)) 108 109 /* How does file close behave? 110 * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL 111 * H5F_CLOSE_WEAK - file closes only after all opened objects are closed 112 * H5F_CLOSE_SEMI - if no opened objects, file is close; otherwise, file 113 close fails 114 * H5F_CLOSE_STRONG - if there are opened objects, close them first, then 115 close file 116 */ 117 typedef enum H5F_close_degree_t { 118 H5F_CLOSE_DEFAULT = 0, 119 H5F_CLOSE_WEAK = 1, 120 H5F_CLOSE_SEMI = 2, 121 H5F_CLOSE_STRONG = 3 122 } H5F_close_degree_t; 123 124 /* Current "global" information about file */ 125 typedef struct H5F_info2_t { 126 struct { 127 unsigned version; /* Superblock version # */ 128 hsize_t super_size; /* Superblock size */ 129 hsize_t super_ext_size; /* Superblock extension size */ 130 } super; 131 struct { 132 unsigned version; /* Version # of file free space management */ 133 hsize_t meta_size; /* Free space manager metadata size */ 134 hsize_t tot_space; /* Amount of free space in the file */ 135 } free; 136 struct { 137 unsigned version; /* Version # of shared object header info */ 138 hsize_t hdr_size; /* Shared object header message header size */ 139 H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ 140 } sohm; 141 } H5F_info2_t; 142 143 /* 144 * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT 145 * should not change other than adding new types to the end. These numbers 146 * might appear in files. 147 * 148 * Note: please change the log VFD flavors array if you change this 149 * enumeration. 150 */ 151 typedef enum H5F_mem_t { 152 H5FD_MEM_NOLIST = -1, /* Data should not appear in the free list. 153 * Must be negative. 154 */ 155 H5FD_MEM_DEFAULT = 0, /* Value not yet set. Can also be the 156 * datatype set in a larger allocation 157 * that will be suballocated by the library. 158 * Must be zero. 159 */ 160 H5FD_MEM_SUPER = 1, /* Superblock data */ 161 H5FD_MEM_BTREE = 2, /* B-tree data */ 162 H5FD_MEM_DRAW = 3, /* Raw data (content of datasets, etc.) */ 163 H5FD_MEM_GHEAP = 4, /* Global heap data */ 164 H5FD_MEM_LHEAP = 5, /* Local heap data */ 165 H5FD_MEM_OHDR = 6, /* Object header data */ 166 167 H5FD_MEM_NTYPES /* Sentinel value - must be last */ 168 } H5F_mem_t; 169 170 /* Free space section information */ 171 typedef struct H5F_sect_info_t { 172 haddr_t addr; /* Address of free space section */ 173 hsize_t size; /* Size of free space section */ 174 } H5F_sect_info_t; 175 176 /* Library's format versions */ 177 typedef enum H5F_libver_t { 178 H5F_LIBVER_ERROR = -1, 179 H5F_LIBVER_EARLIEST = 0, /* Use the earliest possible format for storing objects */ 180 H5F_LIBVER_V18 = 1, /* Use the latest v18 format for storing objects */ 181 H5F_LIBVER_V110 = 2, /* Use the latest v10 format for storing objects */ 182 H5F_LIBVER_NBOUNDS 183 } H5F_libver_t; 184 185 #define H5F_LIBVER_LATEST H5F_LIBVER_V110 186 187 /* File space handling strategy */ 188 typedef enum H5F_fspace_strategy_t { 189 H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /* Mechanisms: free-space managers, aggregators, and virtual file drivers */ 190 /* This is the library default when not set */ 191 H5F_FSPACE_STRATEGY_PAGE = 1, /* Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */ 192 H5F_FSPACE_STRATEGY_AGGR = 2, /* Mechanisms: aggregators and virtual file drivers */ 193 H5F_FSPACE_STRATEGY_NONE = 3, /* Mechanisms: virtual file drivers */ 194 H5F_FSPACE_STRATEGY_NTYPES /* must be last */ 195 } H5F_fspace_strategy_t; 196 197 /* Deprecated: File space handling strategy for release 1.10.0 */ 198 /* They are mapped to H5F_fspace_strategy_t as defined above from release 1.10.1 onwards */ 199 typedef enum H5F_file_space_type_t { 200 H5F_FILE_SPACE_DEFAULT = 0, /* Default (or current) free space strategy setting */ 201 H5F_FILE_SPACE_ALL_PERSIST = 1, /* Persistent free space managers, aggregators, virtual file driver */ 202 H5F_FILE_SPACE_ALL = 2, /* Non-persistent free space managers, aggregators, virtual file driver */ 203 /* This is the library default */ 204 H5F_FILE_SPACE_AGGR_VFD = 3, /* Aggregators, Virtual file driver */ 205 H5F_FILE_SPACE_VFD = 4, /* Virtual file driver */ 206 H5F_FILE_SPACE_NTYPES /* must be last */ 207 } H5F_file_space_type_t; 208 209 /* Data structure to report the collection of read retries for metadata items with checksum */ 210 /* Used by public routine H5Fget_metadata_read_retry_info() */ 211 #define H5F_NUM_METADATA_READ_RETRY_TYPES 21 212 typedef struct H5F_retry_info_t { 213 unsigned nbins; 214 uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES]; 215 } H5F_retry_info_t; 216 217 /* Callback for H5Pset_object_flush_cb() in a file access property list */ 218 typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata); 219 220 221 #ifdef __cplusplus 222 extern "C" { 223 #endif 224 225 /* Functions in H5F.c */ 226 H5_DLL htri_t H5Fis_hdf5(const char *filename); 227 H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, 228 hid_t create_plist, hid_t access_plist); 229 H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, 230 hid_t access_plist); 231 H5_DLL hid_t H5Freopen(hid_t file_id); 232 H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); 233 H5_DLL herr_t H5Fclose(hid_t file_id); 234 H5_DLL hid_t H5Fget_create_plist(hid_t file_id); 235 H5_DLL hid_t H5Fget_access_plist(hid_t file_id); 236 H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned * intent); 237 H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); 238 H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list); 239 H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); 240 H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist); 241 H5_DLL herr_t H5Funmount(hid_t loc, const char *name); 242 H5_DLL hssize_t H5Fget_freespace(hid_t file_id); 243 H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size); 244 H5_DLL herr_t H5Fget_eoa(hid_t file_id, haddr_t *eoa); 245 H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); 246 H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void * buf_ptr, size_t buf_len); 247 H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, 248 H5AC_cache_config_t * config_ptr); 249 H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, 250 H5AC_cache_config_t * config_ptr); 251 H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double * hit_rate_ptr); 252 H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, 253 size_t * max_size_ptr, 254 size_t * min_clean_size_ptr, 255 size_t * cur_size_ptr, 256 int * cur_num_entries_ptr); 257 H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); 258 H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); 259 H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo); 260 H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info); 261 H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id); 262 H5_DLL ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, 263 size_t nsects, H5F_sect_info_t *sect_info/*out*/); 264 H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); 265 H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t high); 266 H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id); 267 H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id); 268 H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, 269 /*OUT*/ hbool_t *is_enabled, 270 /*OUT*/ hbool_t *is_currently_logging); 271 H5_DLL herr_t H5Fformat_convert(hid_t fid); 272 H5_DLL herr_t H5Freset_page_buffering_stats(hid_t file_id); 273 H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], 274 unsigned hits[2], unsigned misses[2], unsigned evictions[2], unsigned bypasses[2]); 275 H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size); 276 277 #ifdef H5_HAVE_PARALLEL 278 H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); 279 H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); 280 #endif /* H5_HAVE_PARALLEL */ 281 282 /* Symbols defined for compatibility with previous versions of the HDF5 API. 283 * 284 * Use of these symbols is deprecated. 285 */ 286 #ifndef H5_NO_DEPRECATED_SYMBOLS 287 288 /* Macros */ 289 #define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /*print debug info (deprecated)*/ 290 291 /* Typedefs */ 292 293 /* Current "global" information about file */ 294 typedef struct H5F_info1_t { 295 hsize_t super_ext_size; /* Superblock extension size */ 296 struct { 297 hsize_t hdr_size; /* Shared object header message header size */ 298 H5_ih_info_t msgs_info; /* Shared object header message index & heap size */ 299 } sohm; 300 } H5F_info1_t; 301 302 303 /* Function prototypes */ 304 H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo); 305 H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format); 306 307 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 308 309 #ifdef __cplusplus 310 } 311 #endif 312 #endif /* _H5Fpublic_H */ 313 314