H5Fpublic.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * This file contains public declarations for the H5F module.
00018  */
00019 #ifndef _H5Fpublic_H
00020 #define _H5Fpublic_H
00021 
00022 /* Public header files needed by this file */
00023 #include "H5public.h"
00024 #include "H5ACpublic.h"
00025 #include "H5Cpublic.h"
00026 #include "H5Ipublic.h"
00027 
00028 /* When this header is included from a private header, don't make calls to H5check() */
00029 #undef H5CHECK
00030 #ifndef _H5private_H
00031 #define H5CHECK          H5check(),
00032 #else   /* _H5private_H */
00033 #define H5CHECK
00034 #endif  /* _H5private_H */
00035 
00036 /*
00037  * These are the bits that can be passed to the `flags' argument of
00038  * H5Fcreate() and H5Fopen(). Use the bit-wise OR operator (|) to combine
00039  * them as needed.  As a side effect, they call H5check_version() to make sure
00040  * that the application is compiled with a version of the hdf5 header files
00041  * which are compatible with the library to which the application is linked.
00042  * We're assuming that these constants are used rather early in the hdf5
00043  * session.
00044  *
00045  */
00046 #define H5F_ACC_RDONLY  (H5CHECK 0x0000u)       /*absence of rdwr => rd-only */
00047 #define H5F_ACC_RDWR    (H5CHECK 0x0001u)       /*open for read and write    */
00048 #define H5F_ACC_TRUNC   (H5CHECK 0x0002u)       /*overwrite existing files   */
00049 #define H5F_ACC_EXCL    (H5CHECK 0x0004u)       /*fail if file already exists*/
00050 #define H5F_ACC_DEBUG   (H5CHECK 0x0008u)       /*print debug info           */
00051 #define H5F_ACC_CREAT   (H5CHECK 0x0010u)       /*create non-existing files  */
00052 
00053 /* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the
00054  * parent file. */
00055 #define H5F_ACC_DEFAULT (H5CHECK 0xffffu)       /*ignore setting on lapl     */
00056 
00057 /* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */
00058 #define H5F_OBJ_FILE    (0x0001u)       /* File objects */
00059 #define H5F_OBJ_DATASET (0x0002u)       /* Dataset objects */
00060 #define H5F_OBJ_GROUP   (0x0004u)       /* Group objects */
00061 #define H5F_OBJ_DATATYPE (0x0008u)      /* Named datatype objects */
00062 #define H5F_OBJ_ATTR    (0x0010u)       /* Attribute objects */
00063 #define H5F_OBJ_ALL     (H5F_OBJ_FILE|H5F_OBJ_DATASET|H5F_OBJ_GROUP|H5F_OBJ_DATATYPE|H5F_OBJ_ATTR)
00064 #define H5F_OBJ_LOCAL   (0x0020u)       /* Restrict search to objects opened through current file ID */
00065                                         /* (as opposed to objects opened through any file ID accessing this file) */
00066 
00067 #define H5F_FAMILY_DEFAULT (hsize_t)0
00068 
00069 #ifdef H5_HAVE_PARALLEL
00070 /*
00071  * Use this constant string as the MPI_Info key to set H5Fmpio debug flags.
00072  * To turn on H5Fmpio debug flags, set the MPI_Info value with this key to
00073  * have the value of a string consisting of the characters that turn on the
00074  * desired flags.
00075  */
00076 #define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key"
00077 #endif /* H5_HAVE_PARALLEL */
00078 
00079 /* The difference between a single file and a set of mounted files */
00080 typedef enum H5F_scope_t {
00081     H5F_SCOPE_LOCAL     = 0,    /*specified file handle only            */
00082     H5F_SCOPE_GLOBAL    = 1     /*entire virtual file                   */
00083 } H5F_scope_t;
00084 
00085 /* Unlimited file size for H5Pset_external() */
00086 #define H5F_UNLIMITED   ((hsize_t)(-1L))
00087 
00088 /* How does file close behave?
00089  * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL
00090  * H5F_CLOSE_WEAK    - file closes only after all opened objects are closed
00091  * H5F_CLOSE_SEMI    - if no opened objects, file is close; otherwise, file
00092                        close fails
00093  * H5F_CLOSE_STRONG  - if there are opened objects, close them first, then
00094                        close file
00095  */
00096 typedef enum H5F_close_degree_t {
00097     H5F_CLOSE_DEFAULT   = 0,
00098     H5F_CLOSE_WEAK      = 1,
00099     H5F_CLOSE_SEMI      = 2,
00100     H5F_CLOSE_STRONG    = 3
00101 } H5F_close_degree_t;
00102 
00103 /* Current "global" information about file */
00104 /* (just size info currently) */
00105 typedef struct H5F_info_t {
00106     hsize_t             super_ext_size; /* Superblock extension size */
00107     struct {
00108         hsize_t         hdr_size;       /* Shared object header message header size */
00109         H5_ih_info_t    msgs_info;      /* Shared object header message index & heap size */
00110     } sohm;
00111 } H5F_info_t;
00112 
00113 /*
00114  * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT
00115  * should not change other than adding new types to the end. These numbers
00116  * might appear in files.
00117  */
00118 typedef enum H5F_mem_t {
00119     H5FD_MEM_NOLIST     = -1,                   /*must be negative*/
00120     H5FD_MEM_DEFAULT    = 0,                    /*must be zero*/
00121     H5FD_MEM_SUPER      = 1,
00122     H5FD_MEM_BTREE      = 2,
00123     H5FD_MEM_DRAW       = 3,
00124     H5FD_MEM_GHEAP      = 4,
00125     H5FD_MEM_LHEAP      = 5,
00126     H5FD_MEM_OHDR       = 6,
00127 
00128     H5FD_MEM_NTYPES                             /*must be last*/
00129 } H5F_mem_t;
00130 
00131 /* Library's file format versions */
00132 typedef enum H5F_libver_t {
00133     H5F_LIBVER_EARLIEST,        /* Use the earliest possible format for storing objects */
00134     H5F_LIBVER_LATEST           /* Use the latest possible format available for storing objects*/
00135 } H5F_libver_t;
00136 
00137 #ifdef __cplusplus
00138 extern "C" {
00139 #endif
00140 
00141 /* Functions in H5F.c */
00142 H5_DLL htri_t H5Fis_hdf5(const char *filename);
00143 H5_DLL hid_t  H5Fcreate(const char *filename, unsigned flags,
00144                           hid_t create_plist, hid_t access_plist);
00145 H5_DLL hid_t  H5Fopen(const char *filename, unsigned flags,
00146                         hid_t access_plist);
00147 H5_DLL hid_t  H5Freopen(hid_t file_id);
00148 H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope);
00149 H5_DLL herr_t H5Fclose(hid_t file_id);
00150 H5_DLL hid_t  H5Fget_create_plist(hid_t file_id);
00151 H5_DLL hid_t  H5Fget_access_plist(hid_t file_id);
00152 H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned * intent);
00153 H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types);
00154 H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list);
00155 H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle);
00156 H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist);
00157 H5_DLL herr_t H5Funmount(hid_t loc, const char *name);
00158 H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
00159 H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size);
00160 H5_DLL herr_t H5Fget_mdc_config(hid_t file_id,
00161                                 H5AC_cache_config_t * config_ptr);
00162 H5_DLL herr_t H5Fset_mdc_config(hid_t file_id,
00163                                 H5AC_cache_config_t * config_ptr);
00164 H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double * hit_rate_ptr);
00165 H5_DLL herr_t H5Fget_mdc_size(hid_t file_id,
00166                               size_t * max_size_ptr,
00167                               size_t * min_clean_size_ptr,
00168                               size_t * cur_size_ptr,
00169                               int * cur_num_entries_ptr);
00170 H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id);
00171 H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size);
00172 H5_DLL herr_t H5Fget_info(hid_t obj_id, H5F_info_t *bh_info);
00173 
00174 #ifdef __cplusplus
00175 }
00176 #endif
00177 #endif /* _H5Fpublic_H */
00178