Introduction to HDF5 HDF5 User Guide Other HDF5 documents and links |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |
The C Interfaces:
The FORTRAN90 Interfaces:
In general, each FORTRAN90 subroutine performs exactly the same task
as the corresponding C function. The links below go to the C function
descriptions, which serve as general descriptions for both. A button,
under Non-C API(s) at the end of the C function description,
opens an external browser window displaying the FORTRAN90-specific
information. You will probably want to adjust the size and location of
this external window so that both browser windows are visible and to
facilitate moving easily between them.
General Property List Operations
File Creation Properties |
Dataset Creation Properties
|| Available only in the parallel HDF5 library. |
File Access Properties
Dataset Memory and Transfer Properties |
H5Pcreate
(H5P_class_t type
)
H5Pcreate
creates a new property as an instance of some
property list class. The new property list is initialized
with default values for the specified class. The classes are:
H5P_FILE_CREATE
H5P_FILE_ACCESS
H5P_DATASET_CREATE
H5P_DATASET_XFER
H5P_MOUNT
H5Pcreate
creates and returns a new mount property list
initialized with default values.
This property list must eventually be closed with
H5Pclose
;
otherwise, errors are likely to occur.
type
plist
) if successful;
otherwise Fail (-1).
H5Pclose
(hid_t plist
)
H5Pclose
terminates access to a property list.
All property lists should be closed when the application is
finished accessing them.
This frees resources used by the property list.
plist
H5Pget_class
(hid_t plist
)
H5Pget_class
returns the property list class for the
property list identified by the plist
parameter.
Valid property list classes are defined in the description of
H5Pcreate
.
plist
H5Pcopy
(hid_t plist
)
H5Pcopy
copies an existing property list to create
a new property list.
The new property list has the same properties and values
as the original property list.
plist
H5Pget_version
(hid_t plist
,
int * super
,
int * freelist
,
int * stab
,
int * shhdr
)
H5Pget_version
retrieves the version information of various objects
for a file creation property list. Any pointer parameters which are
passed as NULL are not queried.
plist
super
freelist
stab
shhdr
H5Pset_userblock
(hid_t plist
,
hsize_t size
)
H5Pset_userblock
sets the user block size of a
file creation property list.
The default user block size is 0; it may be set to any
power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
plist
size
H5Pget_userblock
(hid_t plist
,
hsize_t * size
)
H5Pget_userblock
retrieves the size of a user block
in a file creation property list.
plist
size
H5Pset_sizes
(hid_t plist
,
size_t sizeof_addr
,
size_t sizeof_size
)
H5Pset_sizes
sets the byte size of the offsets and lengths used to
address objects in an HDF5 file. This function is only valid for
file creation property lists. Passing in a value of 0 for one of the
sizeof parameters retains the current value. The default value
for both values is 4 bytes. Valid values currently are 2, 4, 8 and
16.
plist
sizeof_addr
sizeof_size
H5Pget_sizes
(hid_t plist
,
size_t * sizeof_addr
,
size_t * sizeof_size
)
H5Pget_sizes
retrieves the size of the offsets
and lengths used in an HDF5 file.
This function is only valid for file creation property lists.
plist
size
size
H5Pset_sym_k
(hid_t plist
,
int ik
,
int lk
)
H5Pset_sym_k
sets the size of parameters used to
control the symbol table nodes. This function is only valid
for file creation property lists. Passing in a value of 0 for
one of the parameters retains the current value.
ik
is one half the rank of a tree that stores a symbol
table for a group. Internal nodes of the symbol table are on
average 75% full. That is, the average rank of the tree is
1.5 times the value of ik
.
lk
is one half of the number of symbols that can
be stored in a symbol table node. A symbol table node is the
leaf of a symbol table tree which is used to store a group.
When symbols are inserted randomly into a group, the group's
symbol table nodes are 75% full on average. That is, they
contain 1.5 times the number of symbols specified by
lk
.
plist
ik
lk
H5Pget_sym_k
(hid_t plist
,
int * ik
,
int * lk
)
H5Pget_sym_k
retrieves the size of the
symbol table B-tree 1/2 rank and the symbol table leaf
node 1/2 size. This function is only valid for file creation
property lists. If a parameter valued is set to NULL, that
parameter is not retrieved. See the description for
H5Pset_sym_k for more
information.
plist
ik
size
H5Pset_istore_k
(hid_t plist
,
int ik
)
H5Pset_istore_k
sets the size of the parameter
used to control the B-trees for indexing chunked datasets.
This function is only valid for file creation property lists.
Passing in a value of 0 for one of the parameters retains
the current value.
ik
is one half the rank of a tree that stores
chunked raw data. On average, such a tree will be 75% full,
or have an average rank of 1.5 times the value of
ik
.
plist
ik
H5Pget_istore_k
(hid_t plist
,
int * ik
)
H5Pget_istore_k
queries the 1/2 rank of
an indexed storage B-tree.
The argument ik
may be the null pointer (NULL).
This function is only valid for file creation property lists.
See H5Pset_istore_k for details.
plist
ik
H5Pset_layout
(hid_t plist
,
H5D_layout_t layout
)
H5Pset_layout
sets the type of storage used store the
raw data for a dataset.
This function is only valid for dataset creation property lists.
Valid parameters for layout
are:
plist
layout
H5Pget_layout
(hid_t plist
)
H5Pget_layout
returns the layout of the raw data for
a dataset. This function is only valid for dataset creation
property lists. Valid types for layout
are:
plist
H5Pset_chunk
(hid_t plist
,
int ndims
,
const hsize_t * dim
)
H5Pset_chunk
sets the size of the chunks used to
store a chunked layout dataset. This function is only valid
for dataset creation property lists.
The ndims
parameter currently must be the same size
as the rank of the dataset. The values of the dim
array define the size of the chunks to store the dataset's raw data.
As a side-effect, the layout of the dataset is changed to
H5D_CHUNKED
, if it is not already.
plist
ndims
dim
H5Pget_chunk
(hid_t plist
,
int max_ndims
,
hsize_t * dims
)
H5Pget_chunk
retrieves the size of chunks for the
raw data of a chunked layout dataset.
This function is only valid for dataset creation property lists.
At most, max_ndims
elements of dims
will be initialized.
plist
max_ndims
dims
array.
dims
H5Pset_alignment
(hid_t plist
,
hsize_t threshold
,
hsize_t alignment
)
H5Pset_alignment
sets the alignment properties
of a file access property list
so that any file object greater than or equal in size to
threshold
bytes will be aligned on an address
which is a multiple of alignment
. The addresses
are relative to the end of the user block; the alignment is
calculated by subtracting the user block size from the
absolute file address and then adjusting the address to be a
multiple of alignment
.
Default values for threshold
and
alignment
are one, implying
no alignment. Generally the default values will result in
the best performance for single-process access to the file.
For MPI-IO and other parallel systems, choose an alignment
which is a multiple of the disk block size.
plist
threshold
alignment
H5Pget_alignment
(hid_t plist
,
hsize_t *threshold
,
hsize_t *alignment
)
H5Pget_alignment
retrieves the current settings for
alignment properties from a file access property list.
The threshold
and/or alignment
pointers
may be null pointers (NULL).
plist
*threshold
*alignment
H5Pset_external
(hid_t plist
,
const char *name
,
off_t offset
,
hsize_t size
)
H5Pset_external
adds an external file to the
list of external files.
If a dataset is split across multiple files then the files
should be defined in order. The total size of the dataset is
the sum of the size
arguments for all the external files. If
the total size is larger than the size of a dataset then the
dataset can be extended (provided the data space also allows
the extending).
The size
argument specifies number of bytes reserved
for data in the external file.
If size
is set to H5F_UNLIMITED
, the
external file can be of unlimited size and no more files can be added to
the external files list.
plist
*name
offset
size
H5Pget_external_count
(hid_t plist
)
H5Pget_external_count
returns the number of external files
for the specified dataset.
plist
H5Pget_external
(hid_t plist
,
int idx
,
size_t name_size
,
char *name
,
off_t *offset
,
hsize_t *size
)
H5Pget_external
returns information about an external
file. The external file is specified by its index, idx
,
which is a number from zero to N-1, where N is the value
returned by H5Pget_external_count
.
At most name_size
characters are copied into the
name
array. If the external file name is
longer than name_size
with the null terminator, the
return value is not null terminated (similar to strncpy()
).
If name_size
is zero or name
is the
null pointer, the external file name is not returned.
If offset
or size
are null pointers
then the corresponding information is not returned.
plist
idx
name_size
name
array.
*name
*offset
*size
H5Pset_fill_value
(hid_t plist_id
,
hid_t type_id
,
const void *value
)
H5Pset_fill_value
sets the fill value for a
dataset creation property list.
The value
is interpreted as being of type
type_id
. This need not be the same type
as the dataset, but the library must be able to convert
value
to the dataset type when the dataset
is created.
Creating a contiguous dataset with a fill value can be a very expensive operation since the optimization has not yet been implemented that would delay the writing of the fill values until after some data has been written.
plist_id
type_id
,
value
.
value
H5Pget_fill_value
(hid_t plist_id
,
hid_t type_id
,
void *value
)
H5Pget_fill_value
queries the
fill value property of a dataset creation property list.
The fill value is returned through the value
pointer.
Memory is allocated by the caller.
The fill value will be converted from its current
data type to the type specified by type_id
.
plist_id
type_id
,
value
.
value
H5Pset_filter
(hid_t plist
,
H5Z_filter_t filter
,
unsigned int flags
,
size_t cd_nelmts
,
const unsigned int cd_values[]
)
H5Pset_filter
adds the specified
filter
and corresponding properties to the
end of an output filter pipeline.
If plist
is a dataset creation property list,
the filter is added to the permanent filter pipeline;
if plist
is a dataset transfer property list,
the filter is added to the transient filter pipeline.
The array cd_values
contains
cd_nelmts
integers which are auxiliary data
for the filter. The integer values will be stored in the
dataset object header as part of the filter information.
The flags
argument is a bit vector with
the following fields specifying certain general properties
of the filter:
H5Z_FLAG_OPTIONAL |
If this bit is set then the filter is
optional. If the filter fails (see below) during an
H5Dwrite operation then the filter is
just excluded from the pipeline for the chunk for which
it failed; the filter will not participate in the
pipeline during an H5Dread of the chunk.
This is commonly used for compression filters: if the
compression result would be larger than the input then
the compression filter returns failure and the
uncompressed data is stored in the file. If this bit is
clear and a filter fails then H5Dwrite
or H5Dread also fails. |
plist_id
must be a dataset creation
property list.
plist
filter
flags
cd_nelmts
cd_values
.
cd_values[]
H5Pget_nfilters
(hid_t plist
)
H5Pget_nfilters
returns the number of filters
defined in the filter pipeline associated with the property list
plist
.
In each pipeline, the filters are numbered from 0 through N-1, where N is the value returned by this function. During output to the file, the filters are applied in increasing order; during input from the file, they are applied in decreasing order.
H5Pget_nfilters
returns the number of filters
in the pipeline, including zero (0
) if there
are none.
plist_id
must be a dataset creation
property list.
plist
H5Pget_filter
(hid_t plist
,
int filter_number
,
unsigned int *flags
,
size_t *cd_nelmts
,
unsigned int *cd_values
,
size_t namelen
,
char name[]
)
H5Pget_filter
returns information about a
filter, specified by its filter number, in a filter pipeline,
specified by the property list with which it is associated.
If plist
is a dataset creation property list,
the pipeline is a permanent filter pipeline;
if plist
is a dataset transfer property list,
the pipeline is a transient filter pipeline.
On input, cd_nelmts
indicates the number of entries
in the cd_values
array, as allocated by the caller;
on return,cd_nelmts
contains the number of values
defined by the filter.
filter_number
is a value between zero and
N-1, as described in
H5Pget_nfilters
.
The function will return a negative value if the filter number
is out of range.
If name
is a pointer to an array of at least
namelen
bytes, the filter name will be copied
into that array. The name will be null terminated if
namelen
is large enough. The filter name returned
will be the name appearing in the file, the name registered
for the filter, or an empty string.
The structure of the flags
argument is discussed
in H5Pset_filter
.
plist
must be a dataset creation property
list.
plist
filter_number
flags
cd_nelmts
cd_values
.
cd_values
namelen
name
.
name[]
H5Pset_meta_block_size
(
hid_t fapl_id
,
hsize_t size
)
H5Pset_meta_block_size
sets the
minimum size, in bytes, of metadata block allocations when
H5FD_FEAT_AGGREGATE_METADATA
is set by a VFL driver.
Each raw metadata block is initially allocated to be of the given size. Specific metadata objects (e.g., object headers, local heaps, B-trees) are then sub-allocated from this block.
The default setting is 2048 bytes, meaning that the library
will attempt to aggregate metadata in at least 2K blocks in the file.
Setting the value to 0
(zero) with this function
will turn off metadata aggregation, even if the VFL driver attempts
to use the metadata aggregation strategy.
Metadata aggregation reduces the number of small data objects in the file that would otherwise be required for metadata. The aggregated block of metadata is usually written in a single write action and always in a contiguous block, potentially significantly improving library and application performance.
fapl_id
size
H5Pget_meta_block_size
(
hid_t fapl_id
,
hsize_t *size
)
H5Pget_meta_block_size
returns the current
minimum size, in bytes, of new metadata block allocations.
This setting is retrieved from the file access property list
fapl_id
.
This value is set by
H5Pset_meta_block_size
and is retrieved from the file access property list
fapl_id
.
fapl_id
size
H5Pset_sieve_buf_size
(
hid_t fapl_id
,
hsize_t size
)
H5Pset_sieve_buf_size
sets size
,
the maximum size in bytes of the data sieve buffer, which is
used by file drivers that are capable of using data sieving.
The data sieve buffer is used when performing I/O on datasets in the file. Using a buffer which is large anough to hold several pieces of the dataset being read in for hyperslab selections boosts performance by quite a bit.
The default value is set to 64KB, indicating that file I/O for raw data reads and writes will occur in at least 64KB blocks. Setting the value to 0 with this API function will turn off the data sieving, even if the VFL driver attempts to use that strategy.
fapl_id
size
H5Pget_sieve_buf_size
(
hid_t fapl_id
,
hsize_t *size
)
H5Pget_sieve_buf_size
retrieves, size
,
the current maximum size of the data sieve buffer.
This value is set by
H5Pset_sieve_buf_size
and is retrieved from the file access property list
fapl_id
.
fapl_id
size
H5Pset_gc_reference
(hid_t plist
,
unsigned gc_ref
)
H5Pset_gc_references
sets the flag for
garbage collecting references for the file.
Dataset region references and other reference types use space in an HDF5 file's global heap. If garbage collection is on and the user passes in an uninitialized value in a reference structure, the heap might get corrupted. When garbage collection is off, however, and the user re-uses a reference, the previous heap block will be orphaned and not returned to the free heap space.
When garbage collection is on, the user must initialize the reference structures to 0 or risk heap corruption.
The default value for garbage collecting references is off.
plist
gc_ref
1
) or off (0
).
H5Pget_gc_references
(hid_t plist
,
unsigned *gc_ref
)
H5Pget_gc_references
returns the current setting
for the garbage collection references property from
the specified file access property list.
The garbage collection references property is set
by H5Pset_gc_references.
plist
gc_ref
1
indicates that
garbage collection is on while
0
indicates that garbage collection is off.
H5Pset_cache
(hid_t plist_id
,
int mdc_nelmts
,
int rdcc_nelmts
,
size_t rdcc_nbytes
,
double rdcc_w0
)
H5Pset_cache
sets
the number of elements (objects) in the meta data cache and
the number of elements, the total number of bytes, and
the preemption policy value in the raw data chunk cache.
The plist_id is a file access property list. The number of elements (objects) in the meta data cache and the raw data chunk cache are mdc_nelmts and rdcc_nelmts, respectively. The total size of the raw data chunk cache and the preemption policy are rdcc_nbytes and rdcc_w0.
Any (or all) of the H5Pget_cache
pointer arguments
may be null pointers.
The rdcc_w0 value should be between 0 and 1 inclusive and indicates how much chunks that have been fully read are favored for preemption. A value of zero means fully read chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of one means fully read chunks are always preempted before other chunks.
plist_id
mdc_nelmts
rdcc_nelmts
rdcc_nbytes
rdcc_w0
H5Pget_cache
(hid_t plist_id
,
int *mdc_nelmts
,
int *rdcc_nelmts
,
size_t *rdcc_nbytes
,
double *rdcc_w0
)
H5Pget_cache
retrieves the maximum possible
number of elements in the meta
data cache and raw data chunk cache, the maximum possible number of
bytes in the raw data chunk cache, and the preemption policy value.
Any (or all) arguments may be null pointers, in which case the corresponding datum is not returned.
plist_id
*mdc_nelmts
*rdcc_nelmts
*rdcc_nbytes
*rdcc_w0
H5Pset_hyper_cache
(hid_t plist
,
unsigned cache
,
unsigned limit
)
H5Pset_hyper_cache
indicates whether to cache hyperslab blocks during I/O,
a process which can significantly increase I/O speeds.
When working with hyperslab selections, it is possible to
significantly speed up I/O operations by retrieving an
entire hyperslab from the file in one operation and
caching it in memory.
The cache
parameter specifies whether to turn
caching on for hyperslab I/O operations.
If cache
is set to 1
,
caching is turned on;
if set to 0
, caching is turned off.
The parameter limit
sets the maximum size of the
hyperslab block to cache. If a block is smaller than that limit,
it may still not be cached if no memory is available.
Setting limit
to 0
(zero) indicates
no limitation on the size of block to attempt to cache.
The default is to cache blocks with no limit on block size for serial I/O and to not cache blocks for parallel I/O.
plist
cache
1
) or off (0
).
limit
0
(zero) indicates no limit.
H5Pget_hyper_cache
(hid_t plist
,
unsigned *cache
,
unsigned *limit
)
H5Pget_hyper_cache
returns instructions regarding the caching of hyperslab blocks during I/O.
These parameters are set with the H5Pset_hyper_cache
function.
plist
cache
1
) or off (0
).
limit
0
(zero) indicates no limit.
H5Pset_btree_ratios
(hid_t plist
,
double left
,
double middle
,
double right
)
H5Pset_btree_ratios
sets the B-tree split ratios
for a dataset transfer property list. The split ratios determine
what percent of children go in the first node when a node splits.
The ratio left
is used when the splitting node is
the left-most node at its level in the tree;
the ratio right
is used when the splitting node is
the right-most node at its level;
and the ratio middle
is used for all other cases.
A node which is the only node at its level in the tree uses
the ratio right
when it splits.
All ratios are real numbers between 0 and 1, inclusive.
plist
left
right
middle
H5Pget_btree_ratios
(hid_t plist
,
double *left
,
double *middle
,
double *right
)
H5Pget_btree_ratios
returns the B-tree split ratios
for a dataset transfer property list.
The B-tree split ratios are returned through the non-NULL
arguments left
, middle
, and right
,
as set by the H5Pset_btree_ratios function.
plist
left
right
middle
H5Pset_buffer
(hid_t plist
,
hsize_t size
,
void *tconv
,
void *bkg
)
H5Pset_buffer
sets the maximum size
for the type conversion buffer and background buffer and
optionally supplies pointers to application-allocated buffers.
If the buffer size is smaller than the entire amount of data
being transferred between the application and the file, and a type
conversion buffer or background buffer is required, then
strip mining will be used.
Note that there are minimum size requirements for the buffer. Strip mining can only break the data up along the first dimension, so the buffer must be large enough to accommodate a complete slice that encompasses all of the remaining dimensions. For example, when strip mining a 100x200x300 hyperslab of a simple data space, the buffer must be large enough to hold 1x200x300 data elements. When strip mining a 100x200x300x150 hyperslab of a simple data space, the buffer must be large enough to hold 1x200x300x150 data elements.
If tconv
and/or bkg
are null pointers,
then buffers will be allocated and freed during the data transfer.
The default value for the maximum buffer is 1 Mb.
plist
size
tconv
bkg
H5Pget_buffer
(hid_t plist
,
void **tconv
,
void **bkg
)
H5Pget_buffer
reads values previously set
with H5Pset_buffer.
plist
**tconv
**bkg
H5Pset_preserve
(hid_t plist
,
hbool_t status
)
H5Pset_preserve
sets the
dataset transfer property list status to TRUE or FALSE.
When reading or writing compound data types and the destination is partially initialized and the read/write is intended to initialize the other members, one must set this property to TRUE. Otherwise the I/O pipeline treats the destination datapoints as completely uninitialized.
plist
status
H5Pget_preserve
(hid_t plist
)
H5Pget_preserve
checks the status of the
dataset transfer property list.
plist
H5Pset_deflate
(hid_t plist
,
int level
)
H5Pset_deflate
sets the compression method for a
dataset creation property list to H5D_COMPRESS_DEFLATE
and the compression level to level
, which should
be a value from zero to nine, inclusive.
Lower compression levels are faster but result in less compression.
This is the same algorithm as used by the GNU gzip program.
plist
level
H5Pset_vlen_mem_manager
(hid_t plist
,
H5MM_allocate_t alloc
,
void *alloc_info
,
H5MM_free_t free
,
void *free_info
)
H5Dread
and H5Dvlen_reclaim
.
H5Pset_vlen_mem_manager
sets the memory manager for
variable-length datatype allocation in H5Dread
and free in H5Dvlen_reclaim
.
The alloc
and free
parameters
identify the memory management routines to be used.
If the user has defined custom memory management routines,
alloc
and/or free
should be set to make
those routine calls (i.e., the name of the routine is used as
the value of the parameter);
if the user prefers to use the system's malloc
and/or free
, the alloc
and
free
parameters, respectively, should be set to
NULL
The prototypes for these user-defined functions would appear as follows:
typedef void *(*H5MM_allocate_t
)(size_t size
,
void *alloc_info
) ;
typedef void (*H5MM_free_t
)(void *mem
,
void *free_info
) ;
The alloc_info
and free_info
parameters
can be used to pass along any required information to
the user's memory management routines.
In summary, if the user has defined custom memory management
routines, the name(s) of the routines are passed in the
alloc
and free
parameters and the
custom routines' parameters are passed in the
alloc_info
and free_info
parameters.
If the user wishes to use the system malloc
and
free
functions, the alloc
and/or
free
parameters are set to NULL
and the alloc_info
and free_info
parameters are ignored.
plist
alloc
NULL
for system malloc
.
alloc_info
NULL
.
free
NULL
for system free
.
free_info
NULL
.
H5Pget_vlen_mem_manager
(hid_t plist
,
H5MM_allocate_t *alloc
,
void **alloc_info
,
H5MM_free_t *free
,
void **free_info
)
H5Dread
and H5Dvlen_reclaim
.
H5Pget_vlen_mem_manager
is the companion function to
H5Pset_vlen_mem_manager
, returning the parameters
set by that function.
plist
alloc
NULL
for system malloc
.
alloc_info
NULL
.
free
NULL
for
system free
.
free_info
NULL
.
H5Pset_fapl_family
(
hid_t fapl_id
,
hsize_t memb_size
,
hid_t memb_fapl_id
)
H5Pset_fapl_family
sets the file access property list
identifier, fapl_id
, to use the family driver.
memb_size
is the size in bytes of each file member
and is used only when creating a new file.
memb_fapl_id
is the identifier of the
file access property list to be used for each family member.
fapl_id
memb_size
memb_fapl_id
H5Pget_fapl_family
(
hid_t fapl_id
,
hsize_t *memb_size
,
hid_t *memb_fapl_id
)
H5Pget_fapl_family
returns file access property list
for use with the family driver.
This information is returned through the output parameters.
fapl_id
memb_size
memb_fapl_id
H5Pset_fapl_log
(
hid_t fapl_id
,
char *logfile
,
int verbosity
)
H5Pset_fapl_log
modifies the
file access property list to use the logging driver
H5FD_LOG
.
There are no driver-specific properties.
logfile
is the name of the file in which the
logging entries are to be recorded.
verbosity
indicates the extent of the logging
activity intended. Valid values are as follows:
0
| Performs no logging. |
1
| Records where writes and reads occur in the file. |
2
| Records where writes and reads occur in the file and what kind of data is written at each location: raw data or any of several types of metadata (object headers, superblock, B-tree data, local headers, or global headers). |
fapl_id
logfile
verbosity
H5Pset_fapl_mpio
(
hid_t fapl_id
,
MPI_Comm comm
,
MPI_Info info
)
H5Pset_fapl_mpio
stores the user-supplied
MPI IO parameters comm
, for communicator, and
info
, for information, in
the file access property list fapl_id
.
That property list can then be used to create and/or open the file.
H5Pset_fapl_mpio
is available only in the
parallel HDF5 library and is not a collective function.
comm
is the MPI communicator to be used for
file open as defined in MPI_FILE_OPEN
of MPI-2.
This function does not create a duplicated communicator.
Modifications to comm
after this function call
returns may have an undetermined effect on the access property list.
Users should not modify the communicator while it is defined
in a property list.
info
is the MPI info object to be used for
file open as defined in MPI_FILE_OPEN
of MPI-2.
This function does not create a duplicated info object.
Any modification to the info object after this function call
returns may have an undetermined effect on the access property list.
Users should not modify the info while it is defined
in a property list.
fapl_id
comm
info
H5Pget_fapl_mpio
(
hid_t fapl_id
,
MPI_Comm *comm
,
MPI_Info *info
)
H5FD_MPIO
driver, H5Pget_fapl_mpio
returns the MPI communicator and
information through the comm
and info
pointers, if those values are non-null.
Neither comm
nor info
is copied,
so they are valid only until the file access property list
is either modified or closed.
fapl_id
comm
info
H5Pset_dxpl_mpio
(
hid_t dxpl_id
,
H5FD_mpio_xfer_t xfer_mode
)
H5Pset_dxpl_mpio
sets the data transfer property list
dxpl_id
to use transfer mode xfer_mode
.
The property list can then be used to control the I/O transfer mode
during data I/O operations.
Valid transfer modes are as follows:
H5FD_MPIO_INDEPENDENT
H5FD_MPIO_COLLECTIVE
dxpl_id
xfer_mode
H5Pget_dxpl_mpio
(
hid_t dxpl_id
,
H5FD_mpio_xfer_t *xfer_mode
)
H5Pget_dxpl_mpio
queries the data transfer mode
currently set in the data transfer property list dxpl_id
.
Upon return, xfer_mode
contains the data transfer mode,
if it is non-null.
H5Pget_dxpl_mpio
is not a collective function.
dxpl_id
xfer_mode
H5Pset_fapl_multi
(
hid_t fapl_id
,
const H5FD_mem_t *memb_map
,
const hid_t *memb_fapl
,
const char **memb_name
,
const haddr_t *memb_addr
,
hbool_t relax
)
H5Pset_fapl_multi
sets the file access property list
fapl_id
to use the multi-file driver.
The multi-file driver enables different types of HDF5 data and metadata to be written to separate files. These files are viewed by the HDF5 library and the application as a single virtual HDF5 file with a single HDF5 file address space. The types of data that can be broken out into separate file include raw data, the superblock, B-tree data, global heap data, local heap data, and object headers. At the programmer's discretion, two or more types of data can be written the same file while other types of data are written to separate files.
The array memb_map
maps memory usage types to other
memory usage types and is the mechanism that allows the caller
to specify how many files are created.
The array contains H5FD_MEM_NTYPES
entries,
which are either the value H5FD_MEM_DEFAULT
or a memory usage type.
The number of unique values determines the number of files
that are opened.
The array memb_fapl
contains a property list
for each memory usage type that will be associated with a file.
The array memb_name
should be a name generator
(a printf-style format with a %s which will be replaced with the
name passed to H5FDopen
, usually from
H5Fcreate
or H5Fopen
).
The array memb_addr
specifies the offsets within the
virtual address space, from 0
(zero) to
HADDR_MAX
, at wihch each type of data storage begins.
If relax
is set to TRUE
(or 1
),
then opening an existing file for read-only access will not fail
if some file members are missing.
This allows a file to be accessed in a limited sense if just the
meta data is available.
Default values for each of the optional arguments are as follows:
memb_map
H5FD_MEM_DEFAULT
for each element.
memb_fapl
H5P_DEFAULT
for each element.
memb_name
%s-X.h5
where X
is one of the
following letters:
s
for H5FD_MEM_SUPER
b
for H5FD_MEM_BTREE
r
for H5FD_MEM_DRAW
g
for H5FD_MEM_GHEAP
l
for H5FD_MEM_LHEAP
o
for H5FD_MEM_OHDR
memb_addr
HADDR_UNDEF
for each element.
fapl_id
memb_map
memb_fapl
memb_name
memb_addr
0
(zero) to HADDR_MAX
,
at wihch each type of data storage begins.
relax
TRUE
.
H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES]; hid_t memb_fapl[H5FD_MEM_NTYPES]; const char *memb[H5FD_MEM_NTYPES]; haddr_t memb_addr[H5FD_MEM_NTYPES]; // The mapping... for (mt=0; mt<H5FD_MEM_NTYPES; mt++) { memb_map[mt] = H5FD_MEM_SUPER; } memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW; // Member information memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT; memb_name[H5FD_MEM_SUPER] = "%s.meta"; memb_addr[H5FD_MEM_SUPER] = 0; memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT; memb_name[H5FD_MEM_DRAW] = "%s.raw"; memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2; hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); H5Pset_fapl_multi(fapl, memb_map, memb_fapl, memb_name, memb_addr, TRUE);
H5Pget_fapl_multi
(
hid_t fapl_id
,
const H5FD_mem_t *memb_map
,
const hid_t *memb_fapl
,
const char **memb_name
,
const haddr_t *memb_addr
,
hbool_t *relax
)
H5Pget_fapl_multi
returns information about the
multi-file access property list.
fapl_id
memb_map
memb_fapl
memb_name
memb_addr
relax
TRUE
.
H5Pset_dxpl_multi
(
hid_t dxpl_id
,
const hid_t *memb_dxpl
)
H5Pset_dxpl_multi
sets the data transfer property list
dxpl_id
to use the multi-file driver for each
memory usage type memb_dxpl[]
.
H5Pset_dxpl_multi
can only be used after
the member map has been set with H5Pset_fapl_multi
.
dxpl_id
,
memb_dxpl
H5Pget_dxpl_multi
(
hid_t dxpl_id
,
const hid_t *memb_dxpl
)
H5Pget_dxpl_multi
returns the data transfer property list
information for the multi-file driver.
dxpl_id
,
memb_dxpl
H5Pset_fapl_split
(
hid_t fapl_id
,
const char *meta_ext
,
hid_t meta_plist_id
,
const char *raw_ext
,
hid_t raw_plist_id
)
H5Pset_fapl_split
is a compatability function that
enables the multi-file driver to emulate the split driver from
HDF5 Releases 1.0 and 1.2.
The split file driver stored metadata and raw data in separate files
but provide no mechanism for separating types of metadata.
fapl_id
is a file access property list identifier.
meta_ext
is the filename extension for the metadata file.
The extension is appended to the name passed to H5FDopen
,
usually from H5Fcreate
or H5Fopen
,
to form the name of the metadata file.
If the string %s is used in the extension, it works like the
name generator as in H5Pset_fapl_multi
.
meta_plist_id
is the file access property list identifier
for the metadata file.
raw_ext
is the filename extension for the raw data file.
The extension is appended to the name passed to H5FDopen
,
usually from H5Fcreate
or H5Fopen
,
to form the name of the rawdata file.
If the string %s is used in the extension, it works like the
name generator as in H5Pset_fapl_multi
.
raw_plist_id
is the file access property list identifier
for the raw data file.
fapl_id
,
meta_ext
,
meta_plist_id
,
raw_ext
,
raw_plist_id
/* Example 1: Both metadata and rawdata files are in the same */ /* directory. Use Station1-m.h5 and Station1-r.h5 as */ /* the metadata and rawdata files. */ hid_t fapl, fid; fapl = H5Pcreate(H5P_FILE_ACCESS); H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT); fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); /* Example 2: metadata and rawdata files are in different */ /* directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as */ /* the metadata and rawdata files. */ hid_t fapl, fid; fapl = H5Pcreate(H5P_FILE_ACCESS); H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT); fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
H5Pset_fapl_sec2
(
hid_t fapl_id
)
H5Pset_fapl_sec2
modifies the file access property list
to use the H5FD_SEC2
driver.
fapl_id
H5Pset_fapl_stdio
(
hid_t fapl_id
)
H5Pset_fapl_stdio
modifies the file access property list
to use the standard I/O driver, H5FD_STDIO
.
fapl_id
H5Pset_fapl_stream
(
hid_t fapl_id
,
H5FD_stream_fapl_t *fapl
)
H5Pset_fapl_stream
sets up the use of the
streaming I/O driver.
fapl_id
is the identifier for the
file access property list currently in use.
fapl
is the file access property list.
The H5FD_stream_fapl_t
struct contains the following
elements:
size_t | increment |
H5FD_STREAM_SOCKET_TYPE | socket |
hbool_t | do_socket_io |
unsigned int | backlog |
H5FD_stream_broadcast_t | broadcast_fn |
void * | broadcast_arg |
increment
specifies how much memory to allocate
each time additional memory is required.
socket
is an external socket descriptor;
if a valid socket argument is provided, that socket will be used.
do_socket_io
is a boolean value specifying whether
to perform I/O on socket
.
backlog
is the argument for the
listen
call.
broadcast_fn
is the broadcast callback function.
broadcast_arg
is the user argument to
the broadcast callback function.
H5Pset_fapl_stream
and H5Pget_fapl_stream
are not intended for use in a parallel environment.
fapl_id
fapl
H5Pget_fapl_stream
(
hid_t fapl_id
,
H5FD_stream_fapl_t *fapl
)
H5Pget_fapl_stream
returns the file access properties
set for the use of the streaming I/O driver.
H5Pset_fapl_stream
and H5Pget_fapl_stream
are not intended for use in a parallel environment.
fapl_id
fapl
H5Pget_driver
(
hid_t plist_id
)
H5Pget_driver
returns the identifier of the
low-level file driver associated with the file access property list
or data transfer propert list plist_id
.
Valid driver identifiers with the standard HDF5 library distribution include the following:
H5FD_CORE H5FD_DPSS H5FD_FAMILY H5FD_GASS H5FD_LOG H5FD_MPIO H5FD_MULTI H5FD_SEC2 H5FD_STDIO H5FD_STREAMIf a user defines and registers custom drivers or if additional drivers are defined in an HDF5 distribution, this list will be longer.
The returned driver identifier is only valid as long as the file driver remains registered.
plist_id
H5Pset_fapl_gass
(
hid_t fapl_id
,
GASS_Info info
)
H5Pset_fapl_gass
stores user-supplied GASS information,
the GASS_Info struct data as passed in info
,
to the file access property list fapl_id
.
fapl_id
can then be used to create and/or open the file.
The GASS_Info object, info
, is used for
file open operations when using GASS in the Globus environment.
Any modification to info
after this function call
returns may have undetermined effect to the access property list.
Users must call H5Pset_fapl_gass
again to setup
the property list.
H5Pset_fapl_gass
is an experimental function.
It is designed for use only when accessing files via the
GASS facility of the Globus environment.
For further information, see
http//www.globus.org/.
fapl_id
,
info
H5Pget_fapl_gass
(
hid_t fapl_id
,
GASS_Info *info
)
fapl_id
is set
for use of the H5FD_GASS
driver,
H5Pget_fapl_gass
returns the GASS_Info
object through the info
pointer.
The GASS_Info information is copied, so it is valid only until the file access property list is modified or closed.
H5Pget_fapl_gass
is an experimental function.
It is designed for use only when accessing files via the
GASS facility of the Globus environment.
For further information, see
http//www.globus.org/.
fapl_id
,
info
H5Pset_fapl_srb
(
hid_t fapl_id
,
SRB_Info info
)
H5Pset_fapl_srb
stores the SRB client-to-server
connection handler SRB_CONN
after the connection
is established and other user-supplied SRB information.
The user-supplied SRB information is contained in the
SRB_Info struct pointed to by info
and is stored in the file access property list fapl_id
.
This information can then be used to create or open a file.
H5Pset_fapl_gass
is an experimental function.
It is designed for use only when accessing files via the
Storage Resource Broker (SRB). For further information, see
http//www.npaci.edu/Research/DI/srb/.
fapl_id
info
H5Pget_fapl_srb
(
hid_t fapl_id
,
SRB_Info *info
)
fapl_id
is set
for use of the H5FD_SRB
driver,
H5Pget_fapl_srb
returns the SRB_Info
object through the info
pointer.
The SRB_Info information is copied, so it is valid only until the file access property list is modified or closed.
H5Pset_fapl_gass
is an experimental function.
It is designed for use only when accessing files via the
Storage Resource Broker (SRB). For further information, see
http//www.npaci.edu/Research/DI/srb/.
fapl_id
info
H5Pset_fapl_core
(
hid_t fapl_id
,
size_t increment
,
hbool_t backing_store
)
H5FD_CORE
driver.
H5Pset_fapl_core
modifies the file access property list
to use the H5FD_CORE
driver.
The H5FD_CORE
driver enables an application to work
with a file in memory, speeding reads and writes as no disk access
is made. File contents are stored only in memory until the file
is closed. The backing_store
parameter determines
whether file contents are ever written to disk.
increment
specifies the increment by which allocated
memory is to be increased each time more memory is required.
If backing_store
is set to 1
(TRUE
), the file contents are flushed to a file
with the same name as this core file when the file is closed
or access to the file is terminated in memory.
H5FD_CORE
driver to manipulate the file.
fapl_id
increment
backing_store
H5Pget_fapl_core
(
hid_t fapl_id
,
size_t *increment
,
hbool_t *backing_store
)
H5Pget_fapl_core
queries the H5FD_CORE
driver properties as set by H5Pset_fapl_core
.
fapl_id
increment
backing_store
Introduction to HDF5 HDF5 User Guide Other HDF5 documents and links |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |