HDF5: API Specification

  1. Library - H5<name> - API for global library HDF information/modification
    1. H5dont_atexit
    2. H5close
    3. H5version
  2. File - H5F<name> - API for accessing HDF files
    1. H5Fopen
    2. H5Fcreate
    3. H5Fis_hdf5
    4. H5Fget_create_template
    5. H5Fclose
  3. Template - H5P<name> - API for manipulating object templates
    1. H5Pcreate
    2. H5Pget_class
    3. H5Pcopy
    4. H5Pclose
    5. H5Pget_version
    6. H5Pset_userblock
    7. H5Pget_userblock
    8. H5Pset_sizes
    9. H5Pget_sizes
    10. H5Pset_mpi
    11. H5Pget_mpi
    12. H5Pset_xfer
    13. H5Pget_xfer
    14. H5Pset_sym_k
    15. H5Pget_sym_k
    16. H5Pset_istore_k
    17. H5Pget_istore_k
    18. H5Pset_layout
    19. H5Pget_layout
    20. H5Pset_chunk
    21. H5Pget_chunk
  4. Dataset - H5D<name> - API for manipulating scientific datasets. See datasets.
    1. H5Dcreate
    2. H5Dopen
    3. H5Dget_space
    4. H5Dget_type
    5. H5Dget_create_parms
    6. H5Dread
    7. H5Dwrite
    8. H5Dextend
    9. H5Dclose
  5. Datatype - H5T<name> - API for defining dataset element information. See data types.
    1. H5Tcreate
    2. H5Tcopy
    3. H5Tequal
    4. H5Tlock
    5. H5Tget_class
    6. H5Tget_size
    7. H5Tset_size
    8. H5Tget_order
    9. H5Tset_order
    10. H5Tget_precision
    11. H5Tset_precision
    12. H5Tget_offset
    13. H5Tset_offset
    14. H5Tget_pad
    15. H5Tset_pad
    16. H5Tget_sign
    17. H5Tset_sign
    18. H5Tget_fields
    19. H5Tset_fields
    20. H5Tget_ebias
    21. H5Tset_ebias
    22. H5Tget_norm
    23. H5Tset_norm
    24. H5Tget_inpad
    25. H5Tset_inpad
    26. H5Tget_cset
    27. H5Tset_cset
    28. H5Tget_strpad
    29. H5Tset_strpad
    30. H5Tget_nmembers
    31. H5Tget_member_name
    32. H5Tget_member_offset
    33. H5Tget_member_dims
    34. H5Tget_member_type
    35. H5Tinsert
    36. H5Tpack
    37. H5Tregister_hard
    38. H5Tregister_soft
    39. H5Tunregister
    40. H5Tclose
  6. Dataspace - H5S<name> - API for defining dataset dataspace
    1. H5Screate_simple
    2. H5Scopy
    3. H5Sget_npoints
    4. H5Sget_ndims
    5. H5Sget_dims
    6. H5Sis_simple
    7. H5Sset_space
    8. H5Sset_hyperslab
    9. H5Sget_hyperslab
    10. H5Sclose
  7. Group - H5G<name> - API for creating physical groups of objects on disk.
    1. H5Gcreate
    2. H5Gopen
    3. H5Gset
    4. H5Gpush
    5. H5Gpop
    6. H5Gclose
  8. Glossary - A glossary of data-types used in the APIs
    1. Basic Types
    2. Complex Types
    3. Disk I/O Types

Library API Functions

These functions are designed to provide access to HDF5 application/library behavior. They are used to get information about or change global library parameters.


Name: H5dont_atexit
Signature:
herr_t H5dont_atexit(void)
Description:
This routine indicates to the library that an 'atexit()' cleanup routine should not be installed. The major (only?) purpose for this is in situations where the library is dynamically linked into an application and is un-linked from the application before 'exit()' gets callled. In those situations, a routine installed with 'atexit()' would jump to a routine which was no longer in memory, causing errors. In order to be effective, this routine must be called before any other HDF function calls, and must be called each time the library is loaded/ linked into the application. (the first time and after it's been un-loaded)
Parameters: none
Returns:
zero/negative

Name: H5close
Signature:
herr_t H5close(void)
Description:
This routines flushes all data to disk, closes all file handles and cleans up all memory used by the library. Generally it is installed to be called when the application calls exit, but may be called earlier in event of an emergency shutdown or out of desire to free all resources used by the HDF5 library.
Parameters: none
Returns:
zero/negative

Name: H5version
Signature:
herr_t H5version(uintn *majversion, uintn *minversion, uintn *relversion, uintn *patversion )
Description:
This routine retrieves the major, minor, release and patch versions of the library which is linked to the application.
Parameters:
uintn *majversion
The major version of the library.
uintn *minversion
The minor version of the library.
uintn *relversion
The release number of the library.
uintn *patversion
The patch number of the library.
Returns:
zero/negative

File API Functions

These functions are designed to provide file-level access to HDF5 files. Further manipulation of objects inside a file is performed through one of APIs documented below.


Name: H5Fopen
Signature:
hid_t H5Fopen(const char *name, uintn flags, hid_t access_template )
Description:
This is the primary function for opening existing HDF5 files. The flags parameter determines the file access mode. There is no read flag, all open files are implicitily opened for read access. All flags may be combined with the '|' (boolean OR operator) to change the behavior of the file open call. The access_template parameter is a template containing additional information required for specific methods of access, parallel I/O for example. The paramters for access templates are described in the H5P API documentation.
Parameters:
const char *name
Name of the file to access.
uintn flags
File access flags:
    H5F_ACC_RDWR
    Allow read and write access to file.
hid_taccess_template
Template indicating the file access properties. If parallel file access is desired, this is a collective call according to the communicator stored in the access_template. Use 0 for default access template.
Returns:
An ID (of type hid_t) for the file upon success, otherwise negative

Name: H5Fcreate
Signature:
hid_t H5Fcreate(const char *name, uintn flags, hid_t create_template, hid_t access_template )
Description:
This is the primary function for opening and creating HDF5 files. The flags parameter determines whether an existing file will be overwritten or not. All newly created files are opened for both reading and writing. All flags may be combined with the '|' (boolean OR operator) to change the behavior of the file open call. The create_template and access_template parameters are templates containing additional information required for specific methods of access or particular aspects of the file to set when creating a file. The parameters for creation and access templates are described in the H5P API documentation.
Parameters:
const char *name
Name of the file to access.
uintn flags
File access flags:
    H5F_ACC_TRUNC
    Truncate file, if it already exists. The file will be truncated, erasing all data previously stored in the file.
hid_tcreate_template
File creation template ID, used when modifying default file meta-data
hid_taccess_template
Template indicating the file access properties. If parallel file access is desired, this is a collective call according to the communicator stored in the access_template. Use 0 for default access template.
Returns:
An ID (of type hid_t) for the file upon success, otherwise negative

Name: H5Fis_hdf5
Signature:
hbool_t H5Fis_hdf5(const char *name )
Description:
This function determines whether a file is in the HDF5 format.
Parameters:
const char *name
File name to check format.
Returns:
TRUE/FALSE/negative

Name: H5Fget_create_template
Signature:
hid_t H5Fget_create_template(hid_t file_id )
Description:
This function returns an template ID with a copy of the parameters used to create this file. Useful for duplicating the parameters when creating another file.
Parameters:
hid_t file_id
File ID to get creation template of
Returns:
zero/negative

Name: H5Fclose
Signature:
herr_t H5Fclose(hid_t file_id )
Description:
This function terminates access to an HDF5 file. If this is the last file ID open for a file and if access IDs are still in use, this function will fail.
Parameters:
hid_t file_id
File ID to terminate access to.
Returns:
zero/negative

Template API Functions

These functions manipulate template objects to allow objects which require many different parameters to be easily manipulated.


Name: H5Pcreate
Signature:
hid_t H5Pcreate(H5P_class_t type )
Description:
This function returns a template ID for a copy of the default template of a given type.
Template Types and Uses:
    H5P_FILE_CREATE
    Used to set the metadata information about a file during file creation.
    H5P_FILE_ACCESS
    Used to set I/O access information about a file.
    H5P_DATASET_CREATE
    Used to set information about a dataset when it is created.
    H5P_DATASET_XFER
    Used to set access information about a memory to dataset transfer.
Parameters:
H5P_class_t type
The type of template to create.
Returns:
Valid ID on success, negative on failure

Name: H5Pclose
Signature:
herr_t H5Pclose(hid_t template_id )
Description:
This function terminates access to a template.
Parameters:
hid_t template_id
Template ID to terminate access to.
Returns:
zero/negative

Name: H5Pget_class
Signature:
H5P_class_t H5Pget_class(hid_t template_id )
Description:
This function queries the class of a template ID.
Parameters:
hid_t template_id
Template ID to query.
Returns:
Template class code on success, negative on failure

Name: H5Pcopy
Signature:
hid_t H5Pcopy(hid_t template_id )
Description:
This function makes a copy of a template ID.
Parameters:
hid_t template_id
Template ID to duplicate.
Returns:
Template ID on success, negative on failure

Name: H5Pget_version
Signature:
herr_t H5Pget_version(hid_t template_id, int * boot, int * freelist, int * stab, int * shhdr )
Description:
This function queries the version information of various objects for a file creation template. Any pointer parameters which are passed as NULL are not queried.
Parameters:
hid_t template_id
Template ID to query.
int * boot
Pointer to location to return boot block version number.
int * freelist
Pointer to location to return global freelist version number.
int * stab
Pointer to location to return symbol table version number.
int * shhdr
Pointer to location to return shared object header version number.
Returns:
zero/negative

Name: H5Pset_userblock
Signature:
herr_t H5Pset_userblock(hid_t template_id, hsize_t size )
Description:
This function sets the size of the user-block located at the beginning of an HDF5 file. This function is only valid for file creation templates. The default user-block size is 0. Only values which are powers of 2 larger equal to 512 or larger may be used as a valid user-block size.
Parameters:
hid_t template_id
Template to modify.
hsize_t size
Size of the user-block in bytes.
Returns:
zero/negative

Name: H5Pget_userblock
Signature:
herr_t H5Pget_userblock(hid_t template_id, hsize_t * size )
Description:
This function retrieves the size of the user-block located at the beginning of an HDF5 file. This function is only valid for file creation templates.
Parameters:
hid_t template_id
Template ID to query.
hsize_t * size
Pointer to location to return user-block size.
Returns:
zero/negative

Name: H5Pset_sizes
Signature:
herr_t H5Pset_sizes(hid_t template_id, size_t sizeof_addr, size_t sizeof_size )
Description:
This function 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 templates. 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 currenly are 2, 4, 8 and 16.
Parameters:
hid_t template_id
Template to modify.
size_t sizeof_addr
Size of an object offset in bytes.
size_t sizeof_size
Size of an object length in bytes.
Returns:
zero/negative

Name: H5Pget_sizes
Signature:
herr_t H5Pget_sizes(hid_t template_id, size_t * sizeof_addr, size_t * sizeof_size )
Description:
This function retrieves the size of the offsets and lengths used in an HDF5 file. This function is only valid for file creation templates.
Parameters:
hid_t template_id
Template ID to query.
size_t * size
Pointer to location to return offset size in bytes.
size_t * size
Pointer to location to return length size in bytes.
Returns:
zero/negative

Name: H5Pset_mpi
Signature:
herr_t H5Pset_mpi(hid_t tid, MPI_Comm comm, MPI_Info info )
Description:
Store the access mode for parallel I/O call and the user supplied communicator and info in the access template which can then be used to open file. This function is available only in the parallel HDF5 library.
Parameters:
hid_t tid
ID of template to modify
MPI_Comm comm
MPI communicator to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not make a duplicated communicator. Any modification to comm after this function call returns may have undetermined effect to the access template. Users should call this function again to setup the template.
MPI_Info info
MPI info object to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not make a duplicated info. Any modification to info after this function call returns may have undetermined effect to the access template. Users should call this function again to setup the template.
Returns:
zero/negative

Name: H5Pget_mpi
Signature:
herr_t H5Pget_mpi(hid_t tid, MPI_Comm *comm, MPI_Info *info )
Description:
Retrieves the communicator and info object that have been set by H5Pset_mpi. This function is available only in the parallel HDF5 library.
Parameters:
hid_t tid
ID of a file access property list that has been set successfully by H5Pset_mpi.
MPI_Comm * comm
Pointer to location to return the communicator.
MPI_Info * info
Pointer to location to return the info object.
Returns:
zero/negative

Name: H5Pset_xfer
Signature:
herr_t H5Pset_xfer(hid_t tid, H5D_transfer_t data_xfer_mode )
Description:
Set the transfer mode of the dataset transfer property list. The list can then be used to control the I/O transfer mode during dataset accesses. This function is available only in the parallel HDF5 library and is not a collective function.
Parameters:
hid_t tid
ID of a dataset transfer property list
H5D_transfer_t data_xfer_mode
Data transfer modes:
    H5D_XFER_INDEPENDENT
    Use independent I/O access.
    H5D_XFER_COLLECTIVE
    Use MPI collective I/O access.
Returns:
zero/negative

Name: H5Pget_xfer
Signature:
herr_t H5Pget_xfer(hid_t tid, H5D_transfer_t * data_xfer_mode )
Description:
Retrieves the transfer mode from the dataset transfer property list. This function is available only in the parallel HDF5 library.
Parameters:
hid_t tid
ID of a dataset transfer property list.
H5D_transfer_t * data_xfer_mode
Pointer to location to return the data_xfer_mode.
Returns:
zero/negative

Name: H5Pset_sym_k
Signature:
herr_t H5Pset_sym_k(hid_t template_id, size_t ik, size_t lk )
Description:
This function sets the size of parameters used to control the symbol table nodes. This function is only valid for file creation templates. 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.
Parameters:
hid_t template_id
Template ID to query.
size_t ik
Symbol table tree rank.
size_t lk
Symbol table node size.
Returns:
zero/negative

Name: H5Pget_sym_k
Signature:
herr_t H5Pget_sym_k(hid_t template_id, size_t * ik, size_t * lk )
Description:
This function retrieves the size of the symbol table's B-tree 1/2 rank and the symbol table's leaf node 1/2 size. See information for H5Pset_sym_k for more information. This function is only valid for file creation templates. If a parameter valued is set to NULL, that parameter is not retrieved.
Parameters:
hid_t template_id
Template ID to query.
size_t * ik
Pointer to location to return the symbol table's B-tree 1/2 rank.
size_t * size
Pointer to location to return the symbol table's leaf node 1/2 size.
Returns:
zero/negative

Name: H5Pset_istore_k
Signature:
herr_t H5Pset_istore_k(hid_t template_id, size_t ik )
Description:
This function sets the size of the parameter used to control the B-trees for indexing chunked datasets. This function is only valid for file creation templates. 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.
Parameters:
hid_t template_id
Template ID to query.
size_t ik
1/2 rank of chunked storage B-tree.
Returns:
zero/negative

Name: H5Pget_istore_k
Signature:
herr_t H5Pget_istore_k(hid_t template_id, size_t * ik )
Description:
Queries the 1/2 rank of an indexed storage B-tree. See H5Pset_istore_k for details. The argument ik may be the null pointer. This function is only valid for file creation templates.
Parameters:
hid_t template_id
Template ID to query.
size_t * ik
Pointer to location to return the chunked storage B-tree 1/2 rank.
Returns:
zero/negative

Name: H5Pset_layout
Signature:
herr_t H5Pset_layout(hid_t template_id, H5D_layout_t layout )
Description:
This function sets the type of storage used store the raw data for a dataset. This function is only valid for dataset creation templates. Valid parameter for layout are:
Parameters:
hid_t template_id
Template ID to query.
H5D_layout_t layout
Type of storage layout for raw data.
Returns:
zero/negative

Name: H5Pget_layout
Signature:
herr_t H5Pget_layout(hid_t template_id, H5D_layout_t * layout )
Description:
Queries the layout of the raw data for a dataset. This function is only valid for dataset creation templates. Valid types for layout are:
Parameters:
hid_t template_id
Template ID to query.
H5D_layout_t * layout
Pointer to location to return the storage layout.
Returns:
zero/negative

Name: H5Pset_chunk
Signature:
herr_t H5Pset_chunk(hid_t template_id, int ndims, const hsize_t * dim )
Description:
This function sets the size of the chunks used to store a chunked layout dataset. This function is only valid for dataset creation templates. 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 isn't already.
Parameters:
hid_t template_id
Template ID to query.
int ndims
The number of dimensions of each chunk.
const hsize_t * dim
An array containing the size of each chunk.
Returns:
zero/negative

Name: H5Pget_chunk
Signature:
herr_t H5Pget_chunk(hid_t template_id, int max_ndims hsize_t * dims )
Description:
Queries the size of chunks for the raw data of a chunked layout dataset. This function is only valid for dataset creation templates.
Parameters:
hid_t template_id
Template ID to query.
int max_ndims
Size of the dims array.
hsize_t * dims
Array to store the chunk dimensions.
Returns:
zero/negative

Dataset Object API Functions

These functions create and manipulate dataset objects. Each dataset must be constructed from a datatype and a dataspace.


Name: H5Dcreate
Signature:
hid_t H5Dcreate(hid_t file_id, const char *name, hid_ttype_id, hid_tspace_id, hid_ttemplate_id )
Description:
This function creates a new dataset in the file specified with the file_id. The type_id and space_id are the IDs of the datatype and dataspace used to construct the framework of the dataset. The datatype and dataspace parameters describe the dataset as it will exist in the file, which is not necessarily the same as it exists in memory. The template_id contains either the default template (H5P_DEFAULT) or a template_id with particular constant properties used to create the dataset. The name is used to identify the dataset in a group and must be unique within that group.
Parameters:
hid_t file_id
ID of the file to create the dataset within.
const char * name
The name of the dataset to create.
hid_t type_id
ID of the datatype to use when creating the dataset.
hid_t space_id
ID of the dataspace to use when creating the dataset.
hid_t template_id
ID of the dataset creation template.
Returns:
Dataset ID on success, negative on failure.

Name: H5Dopen
Signature:
hid_t H5Dopen(hid_t file_id, const char *name )
Description:
This function opens an existing dataset for access in the file specified with the file_id. The name is used to identify the dataset in the file.
Parameters:
hid_t file_id
ID of the file to access the dataset within.
const char * name
The name of the dataset to access.
Returns:
Dataset ID on success, negative on failure.

Name: H5Dget_space
Signature:
hid_t H5Dget_space(hid_t dataset_id )
Description:
This function returns a copy of the dataspace for a dataset. The dataspace should be released with the H5Sclose() function.
Parameters:
hid_t dataset_id
ID of the dataset to query.
Returns:
Dataspace ID on success, negative on failure.

Name: H5Dget_type
Signature:
hid_t H5Dget_type(hid_t dataset_id )
Description:
This function returns a copy of the datatype for a dataset. The dataspace should be released with the H5Tclose() function.
Parameters:
hid_t dataset_id
ID of the dataset to query.
Returns:
Datatype ID on success, negative on failure.

Name: H5Dget_create_plist
Signature:
hid_t H5Dget_create_plist(hid_t dataset_id )
Description:
This function returns a copy of the dataset creation template for a dataset. The template should be released with the H5Pclose() function.
Parameters:
hid_t dataset_id
ID of the dataset to query.
Returns:
Dataset creation template ID on success, negative on failure.

Name: H5Dread
Signature:
herr_t H5Dread(hid_t dataset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t transfer_template_id, void * buf )
Description:
This function reads raw data from the specified dataset into buf, converting from the file datatype of the dataset into the memory datatype specified in mem_type_id. The portion of the dataset to read from disk is specified with the file_spaceid which can contain a dataspace with a hyperslab selected or the constant H5S_ALL, which indicates the entire dataset is to be read. The portion of the dataset read into the memory buffer is specified with the mem_space_id which can also be a hyperslab of the same size or the H5S_ALL parameter to store the entire dataset. The transfer_template_id is a dataset transfer template ID which is used to provide addition parameters for the I/O operation or can be H5P_DEFAULT for the default library behavior.
Parameters:
hid_t dataset_id
ID of the dataset read from.
hid_t mem_type_id
ID of the memory datatype.
hid_t mem_space_id
ID of the memory dataspace.
hid_t file_space_id
ID of the dataset's dataspace in the file.
hid_t transfer_template_id
ID of a transfer template for this I/O operation.
void * buf
Buffer to store information read from the file.
Returns:
zero/negative

Name: H5Dwrite
Signature:
herr_t H5Dwrite(hid_t dataset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t transfer_template_id, const void * buf )
Description:
This function writes raw data from memory into the specified dataset converting from the memory datatype of the dataset specified in mem_type_id into the file datatype. The portion of the dataset to written to disk is specified with the file_spaceid which can contain a dataspace with a hyperslab selected or the constant H5S_ALL, which indicates the entire dataset is to be written. The portion of the dataset written from the memory buffer is specified with the mem_space_id which can also be a hyperslab of the same size or the H5S_ALL parameter to store the entire dataset. The transfer_template_id is a dataset transfer template ID which is used to provide addition parameters for the I/O operation or can be H5P_DEFAULT for the default library behavior.
Parameters:
hid_t dataset_id
ID of the dataset read from.
hid_t mem_type_id
ID of the memory datatype.
hid_t mem_space_id
ID of the memory dataspace.
hid_t file_space_id
ID of the dataset's dataspace in the file.
hid_t transfer_template_id
ID of a transfer template for this I/O operation.
const void * buf
Buffer to store information to be written to the file.
Returns:
zero/negative

Name: H5Dextend
Signature:
herr_t H5Dextend(hid_t dataset_id, const hsize_t * size )
Description:
This function increases the size of the dataspace of a dataset with unlimited dimensions. It cannot be used to extend the size of a dataspace's fixed dimensions. The size array must have the same number of entries as the rank of the dataset's dataspace.
Parameters:
hid_t dataset_id
ID of the dataset read from.
const hsize_t * size
Array containing the new magnitude of each dimension.
Returns:
zero/negative

Name: H5Dclose
Signature:
hid_t H5Dclose(hid_t dataset_id )
Description:
This function ends access to a dataset and releases resources used by it. Further use of the dataset ID is illegal in calls to the dataset API.
Parameters:
hid_t dataset_id
ID of the dataset to finish access to.
Returns:
zero/negative

Datatype Object API Functions

These functions create and manipulate the datatype which describes elements of a dataset.


Name: H5Tcreate
Signature:
hid_t H5Tcreate(H5T_class_t class, size_tsize )
Description:
This function creates a new dataype of the specified class with the specified number of bytes. Currently, only the H5T_COMPOUND datatype class is supported with this function, use H5Tcopy to create integer or floating-point datatypes. The datatype ID returned from this function should be released with H5Tclose or resource leaks will result.
Parameters:
H5T_class_t class
Class of datatype to create.
size_t size
The number of bytes in the datatype to create.
Returns:
Datatype ID on success, negative on failure.

Name: H5Tcopy
Signature:
hid_t H5Tcopy(hid_t type_id )
Description:
This function copies an existing datatype. The datatype ID returned should be released with H5Tclose or resource leaks will occur. Native datatypes supported by the library are:
Parameters:
hid_t type_id
ID of datatype to copy.
Returns:
Datatype ID on success, negative on failure.

Name: H5Tequal
Signature:
hbool_t H5Tequal(hid_t type_id1, hid_ttype_id2 )
Description:
This function determines if two datatype IDs refer to the same datatype.
Parameters:
hid_t type_id1
ID of datatype to compare.
hid_t type_id2
ID of datatype to compare.
Returns:
TRUE/FALSE/negative

Name: H5Tlock
Signature:
herr_t H5Tlock(hid_t type_id )
Description:
This function locks a type, making it read-only and non-destrucible. This is normally done by the library for predefined data types so the application doesn't inadvertently change or delete a predefined type. Once a data type is locked it can never be unlocked.
Parameters:
hid_t type_id
ID of datatype to lock.
Returns:
zero/negative

Name: H5Tget_class
Signature:
H5T_class_t H5Tget_class(hid_t type_id )
Description:
This function returns the base class of a datatype.
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Non-negative type class on success, negative on failure.

Name: H5Tget_size
Signature:
size_t H5Tget_size(hid_t type_id )
Description:
This function returns the size of a datatype in bytes.
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Positve size in bytes on success, 0 on failure.

Name: H5Tset_size
Signature:
herr_t H5Tset_size(hid_t type_id, size_tsize )
Description:
This function sets the total size in bytes for an atomic data type (this operation is not permitted on compound data types). If the size is decreased so that the significant bits of the data type extend beyond the edge of the new size, then the `offset' property is decreased toward zero. If the `offset' becomes zero and the significant bits of the data type still hang over the edge of the new size, then the number of significant bits is decreased. Adjusting the size of an H5T_STRING automatically sets the precision to 8*size. All data types have a positive size.
Parameters:
hid_t type_id
ID of datatype to change size.
size_t size
Size in bytes to modify datatype.
Returns:
zero/negative

Name: H5Tget_order
Signature:
H5T_order_t H5Tget_order(hid_t type_id )
Description:
This function returns the byte order of an atomic datatype.
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Byte order constant on success, negative on failure

Name: H5Tset_order
Signature:
herr_t H5Tset_order(hid_t type_id, H5T_order_torder )
Description:
This function sets the byte ordering of an atomic datatype. Byte orderings currently supported are:
Parameters:
hid_t type_id
ID of datatype to set.
H5T_order_t order
Byte ordering constant.
Returns:
zero/negative

Name: H5Tget_precision
Signature:
size_t H5Tget_precision(hid_t type_id )
Description:
This function returns the precision of an atomic data type. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Number of significant bits on success, 0 on failure

Name: H5Tset_precision
Signature:
herr_t H5Tset_precision(hid_t type_id, size_tprecision )
Description:
This function sets the precision of an atomic data type. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().

If the precision is increased then the offset is decreased and then the size is increased to insure that significant bits do not "hang over" the edge of the data type.

Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8.

When decreasing the precision of a floating point type, set the locations and sizes of the sign, mantissa, and exponent fields first.

Parameters:
hid_t type_id
ID of datatype to set.
size_t precision
Number of bits of precision for datatype.
Returns:
zero/negative

Name: H5Tget_offset
Signature:
size_t H5Tget_offset(hid_t type_id )
Description:
This function retrieves the bit offset of the first significant bit. The signficant bits of an atomic datum can be offset from the beginning of the memory for that datum by an amount of padding. The `offset' property specifies the number of bits of padding that appear to the "right of" the value. That is, if we have a 32-bit datum with 16-bits of precision having the value 0x1122 then it will be layed out in memory as (from small byte address toward larger byte addresses):

Byte Position Big-Endian Offset=0 Big-Endian Offset=16 Little-Endian Offset=0 Little-Endian Offset=16
0: [ pad] [0x11] [0x22] [ pad]
1: [ pad] [0x22] [0x11] [ pad]
2: [0x11] [ pad] [ pad] [0x22]
3: [0x22] [ pad] [ pad] [0x11]
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Positive offset value on success, 0 on failure.

Name: H5Tset_offset
Signature:
herr_t H5Tset_offset(hid_t type_id, size_t offset )
Description:
This function sets the bit offset of the first significant bit. The signficant bits of an atomic datum can be offset from the beginning of the memory for that datum by an amount of padding. The `offset' property specifies the number of bits of padding that appear to the "right of" the value. That is, if we have a 32-bit datum with 16-bits of precision having the value 0x1122 then it will be layed out in memory as (from small byte address toward larger byte addresses):

Byte Position Big-Endian Offset=0 Big-Endian Offset=16 Little-Endian Offset=0 Little-Endian Offset=16
0: [ pad] [0x11] [0x22] [ pad]
1: [ pad] [0x22] [0x11] [ pad]
2: [0x11] [ pad] [ pad] [0x22]
3: [0x22] [ pad] [ pad] [0x11]

If the offset is incremented then the total size is incremented also if necessary to prevent significant bits of the value from hanging over the edge of the data type.

The offset of an H5T_STRING cannot be set to anything but zero.

Parameters:
hid_t type_id
ID of datatype to set.
size_t offset
Offset of first significant bit.
Returns:
zero/negative

Name: H5Tget_pad
Signature:
herr_t H5Tget_pad(hid_t type_id, H5T_pad_t * lsb, H5T_pad_t * msb )
Description:
This function retrieves the padding type of the least and most-significant bit padding. Valid types are:
Parameters:
hid_t type_id
ID of datatype to query.
H5T_pad_t * lsb
Pointer to location to return least-significant bit padding type.
H5T_pad_t * msb
Pointer to location to return most-significant bit padding type.
Returns:
zero/negative

Name: H5Tset_pad
Signature:
herr_t H5Tset_pad(hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb )
Description:
This function sets the least and most-significant bits padding types.
Parameters:
hid_t type_id
ID of datatype to set.
H5T_pad_t lsb
Padding type for least-significant bits.
H5T_pad_t msb
Padding type for most-significant bits.
Returns:
zero/negative

Name: H5Tget_sign
Signature:
H5T_sign_t H5Tget_sign(hid_t type_id )
Description:
This function retrieves the sign type for an integer type. Valid types are:
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Non-negative sign type on success, negative on failure

Name: H5Tset_sign
Signature:
herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign )
Description:
This function sets the sign proprety for an integer type.
Parameters:
hid_t type_id
ID of datatype to set.
H5T_sign_t sign
Sign type.
Returns:
zero/negative

Name: H5Tget_fields
Signature:
herr_t H5Tget_fields(hid_t type_id, size_t * epos, size_t * esize, size_t * mpos, size_t * msize )
Description:
This function retrieves information about the locations of the various bit fields of a floating point data type. The field positions are bit positions in the significant region of the data type. Bits are numbered with the least significant bit number zero. Any (or even all) of the arguments can be null pointers.
Parameters:
hid_t type_id
ID of datatype to query.
size_t * epos
Pointer to location to return exponent bit-position.
size_t * esize
Pointer to location to return size of exponent in bits.
size_t * mpos
Pointer to location to return mantissa bit-position.
size_t * msize
Pointer to location to return size of mantissa in bits.
Returns:
zero/negative

Name: H5Tset_fields
Signature:
herr_t H5Tset_fields(hid_t type_id, size_t epos, size_t esize, size_t mpos, size_t msize )
Description:
This function sets the locations and sizes of the various floating point bit fields. The field positions are bit positions in the significant region of the data type. Bits are numbered with the least significant bit number zero.

Fields are not allowed to extend beyond the number of bits of precision, nor are they allowed to overlap with one another.

Parameters:
hid_t type_id
ID of datatype to set.
size_t epos
Exponent bit position.
size_t esize
Size of exponent in bits.
size_t mpos
Mantissa bit position.
size_t msize
Size of mantissa in bits.
Returns:
zero/negative

Name: H5Tget_ebias
Signature:
size_t H5Tget_ebias(hid_t type_id )
Description:
This function retrieves the exponent bias of a floating-point type.
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Positive value on success, 0 on failure.

Name: H5Tset_ebias
Signature:
herr_t H5Tset_ebias(hid_t type_id, size_t ebias )
Description:
This function sets the exponent bias of a floating-point type.
Parameters:
hid_t type_id
ID of datatype to set.
size_t ebias
Exponent bias value.
Returns:
zero/negative

Name: H5Tget_norm
Signature:
H5T_norm_t H5Tget_norm(hid_t type_id )
Description:
This function retrieves the mantissa normalization of a floating-point datatype. Valid normalization values are:
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Non-negative normalization type on success, negative on failure

Name: H5Tset_norm
Signature:
herr_t H5Tset_norm(hid_t type_id, H5T_norm_t norm )
Description:
This function sets the mantissa normalization of a floating-point datatype. Valid normalization values are:
Parameters:
hid_t type_id
ID of datatype to set.
H5T_norm_t norm
Mantissa normalization type.
Returns:
zero/negative

Name: H5Tget_inpad
Signature:
H5T_pad_t H5Tget_inpad(hid_t type_id )
Description:
This function retrieves the internal padding type for unused bits in floating-point datatypes. Valid padding values are:
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Non-negative padding type on success, negative on failure

Name: H5Tset_inpad
Signature:
herr_t H5Tset_inpad(hid_t type_id, H5T_pad_t inpad )
Description:
If any internal bits of a floating point type are unused (that is, those significant bits which are not part of the sign, exponent, or mantissa) then they will be filled according to the value of this property. Valid padding values are:
Parameters:
hid_t type_id
ID of datatype to modify.
H5T_pad_t pad
Padding type.
Returns:
zero/negative

Name: H5Tget_cset
Signature:
H5T_cset_t H5Tget_cset(hid_t type_id )
Description:
This function retrieves the character set type of a string datatype. Valid character set values are:
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Non-negative character set type on success, negative on failure

Name: H5Tset_cset
Signature:
herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset )
Description:
HDF5 is able to distinguish between character sets of different nationalities and to convert between them to the extent possible. Valid character set values are:
Parameters:
hid_t type_id
ID of datatype to modify.
H5T_cset_t cset
Character set type.
Returns:
zero/negative

Name: H5Tget_strpad
Signature:
H5T_str_t H5Tget_strpad(hid_t type_id )
Description:
This function retrieves the string padding method for a string datatype. Valid string padding values are:
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Non-negative string padding type on success, negative on failure

Name: H5Tset_strpad
Signature:
herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad )
Description:
The method used to store character strings differs with the programming language: C usually null terminates strings while Fortran left-justifies and space-pads strings. This property defines the storage mechanism for the string. Valid string padding values are:
Parameters:
hid_t type_id
ID of datatype to modify.
H5T_str_t strpad
String padding type.
Returns:
zero/negative

Name: H5Tget_nmembers
Signature:
intn H5Tget_nmembers(hid_t type_id )
Description:
This function retrieves the number of fields a compound datatype has.
Parameters:
hid_t type_id
ID of datatype to query.
Returns:
Number of members datatype has on success, negative on failure

Name: H5Tget_member_name
Signature:
char * H5Tget_member_name(hid_t type_id, intn fieldno )
Description:
This function retrieves the name of a field of a compound data type. Fields are stored in no particular order with numbers 0 through N-1 where N is the value returned by H5Tget_nmembers(). The name of the field is allocated with malloc() and the caller is responsible for freeing the memory used by the name.
Parameters:
hid_t type_id
ID of datatype to query.
intn fieldno
Field number (indexed from 0) of the field name to retrieve.
Returns:
Valid pointer on success, NULL on failure

Name: H5Tget_member_dims
Signature:
int H5Tget_member_dims(hid_t type_id, intn fieldno, size_t * dims, int * perm )
Description:
This function returns the dimensionality of the field. The dimensions and permuation vector are returned through arguments dims and perm, both arrays of at least four elements. Either (or even both) may be null pointers.
Parameters:
hid_t type_id
ID of datatype to query.
intn fieldno
Field number (indexed from 0) of the field dims to retrieve.
size_t * dims
Pointer to buffer to store the dimensions of the field.
int * perm
Pointer to buffer to store the permutation vector of the field.
Returns:
Number of dimensions on success, negative on failure.

Name: H5Tget_member_type
Signature:
hid_t H5Tget_member_type(hid_t type_id, intn fieldno )
Description:
This function returns the data type of the specified member. The caller should invoke H5Tclose() to release resources associated with the type.
Parameters:
hid_t type_id
ID of datatype to query.
intn fieldno
Field number (indexed from 0) of the field type to retrieve.
Returns:
The ID of a copy of the datatype of the field, negative on failure.

Name: H5Tinsert
Signature:
herr_t H5Tinsert(hid_t type_id, const char * name, off_t offset, hid_t field_id )
Description:
This function adds another member to the compound data type type_id. The new member has a name which must be unique within the compound data type. The offset argument defines the start of the member in an instance of the compound data type, and field_id is the type of the new member.

Note: All members of a compound data type must be atomic; a compound data type cannot have a member which is a compound data type.

Parameters:
hid_t type_id
ID of compound datatype to modify.
const char * name
Name of the field to insert.
off_t offset
Offset in memory structure of the field to insert.
hid_t field_id
Datatype ID of the field to insert.
Returns:
zero/negative

Name: H5Tpack
Signature:
herr_t H5Tpack(hid_t type_id )
Description:
This function recursively removes padding from within a compound datatype to make it more efficient (space-wise) to store that data.
Parameters:
hid_t type_id
ID of datatype to modify.
Returns:
zero/negative

Name: H5Tregister_hard
Signature:
herr_t H5Tregister_hard(const char * name, hid_t src_id, hid_t dst_id, H5T_conv_t func )
Description:
This function registers a hard conversion function for a data type conversion path. The path is specified by the source and destination datatypes src_id and dst_id. A conversion path can only have one hard function, so func replaces any previous hard function.

If func is the null pointer then any hard function registered for this path is removed from this path. The soft functions are then used when determining which conversion function is appropriate for this path. The name argument is used only for debugging and should be a short identifier for the function.

The type of the conversion function pointer is declared as: typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, void *buf, void *bkg);

Parameters:
const char * name
Name displayed in diagnostic output.
hid_t src_id
ID of source datatype.
hid_t dst_id
ID of destination datatype.
H5T_conv_t func
Function to convert between source and destination datatypes.
Returns:
zero/negative

Name: H5Tregister_soft
Signature:
herr_t H5Tregister_soft(const char * name, hid_t src_id, hid_t dst_id, H5T_conv_t func )
Description:
This function registers a soft conversion function by adding it to the end of the master soft list and replacing the soft function in all applicable existing conversion paths. The name is used only for debugging and should be a short identifier for the function.

The type of the conversion function pointer is declared as: typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, void *buf, void *bkg);

Parameters:
const char * name
Name displayed in diagnostic output.
hid_t src_id
ID of source datatype.
hid_t dst_id
ID of destination datatype.
H5T_conv_t func
Function to convert between source and destination datatypes.
Returns:
zero/negative

Name: H5Tunregister
Signature:
herr_t H5Tunregister(H5T_conv_t func )
Description:
This function removes a conversion function from all conversion paths.

The type of the conversion function pointer is declared as: typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, void *buf, void *bkg);

Parameters:
H5T_conv_t func
Function to remove from conversion paths.
Returns:
zero/negative

Name: H5Tclose
Signature:
herr_t H5Tclose(hid_t type_id )
Description:
This function releases a datatype. Further access through the datatype ID is illegal. Failure to release a datatype with this call will result in resource leaks.
Parameters:
hid_t type_id
ID of datatype to release.
Returns:
zero/negative

Dataspace Object API Functions

These functions create and manipulate the dataspace in which to store the elements of a dataset.


Name: H5Screate_simple
Signature:
hid_t H5Screate_simple(int rank, const hsize_t * dims, const hsize_t * maxdims )
Description:
This function creates a new simple data space object and opens it for access. The rank is the number of dimensions used in the dataspace. The dims argument is the size of the simple dataset and the maxdims argument is the upper limit on the size of the dataset. maxdims may be the null pointer in which case the upper limit is the same as dims. If an element of maxdims is zero then the corresponding dimension is unlimited, otherwise no element of maxdims should be smaller than the corresponding element of dims. The dataspace ID returned from this function should be released with H5Sclose or resource leaks will occur.
Parameters:
int rank
Number of dimensions of dataspace.
const hsize_t * dims
An array of the size of each dimension.
const hsize_t * maxdims
An array of the maximum size of each dimension.
Returns:
A dataspace ID on success, negative on failure.

Name: H5Scopy
Signature:
hid_t H5Scopy(hid_t space_id )
Description:
This function copies a dataspace. The dataspace ID returned from this function should be released with H5Sclose or resource leaks will occur.
Parameters:
hid_t space_id
ID of dataspace to copy.
Returns:
A dataspace ID on success, negative on failure.

Name: H5Sget_npoints
Signature:
hsize_t H5Sget_npoints(hid_t space_id)
Description:
This function determines the number of elements in a dataspace. For example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 would have 24 elements.
Parameters:
hid_t space_id
ID of the dataspace object to query
Returns:
Number of elements in the dataspace, 0 on failure

Name: H5Sget_ndims
Signature:
int H5Sget_ndims(hid_t space_id)
Description:
This function determines the dimensionality (or rank) of a dataspace.
Parameters:
hid_t space_id
ID of the dataspace object to query
Returns:
Number of dimensions in the dataspace, negative on failure

Name: H5Sget_dims
Signature:
int H5Sget_dims(hid_t space_id, hsize_t *dims, hsize_t *maxdims )
Description:
This function returns the size of each dimension in a dataspace through the dims parameter.
Parameters:
hid_t space_id
ID of the dataspace object to query
hsize_t *dims
Pointer to array to store the size of each dimension.
hsize_t *maxdims
Pointer to array to store the maximum size of each dimension.
Returns:
Number of dimensions in the dataspace, negative on failure

Name: H5Sis_simple
Signature:
hbool_t H5Sis_simple(hid_t space_id)
Description:
This function determines whether a dataspace object is a simple dataspace or not. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future]
Parameters:
hid_t space_id
ID of the dataspace object to query
Returns:
TRUE or FALSE on success, negative on failure

Name: H5Sset_space
Signature:
herr_t H5Sset_space(hid_t space_id, uint32 rank, uint32 *dims )
Description:
This function determines the number of dimensions and the size of each dimension for the space that a dataset is stored within. This function only creates simple dataspace objects. Setting the rank to a value of zero allows scalar objects to be created. Dimensions are specified from slowest to fastest changing in the dims array (i.e. 'C' order). Setting the size of a dimension to zero indicates that the dimension is of unlimited size and should be allowed to expand. Currently, only the first dimension in the array (the slowest) may be unlimited in size. [Currently, all dataspace objects are simple dataspaces, complex dataspace support will be added in the future]
Parameters:
hid_t space_id
ID of the dataspace object.
uint32 rank
The number of dimensions the object is composed of.
uint32 * dims
An array of the size of each dimension. (NULL for scalar objects)
Returns:
zero/negative

Name: H5Sset_hyperslab
Signature:
herr_t H5Sset_hyperslab(hid_t space_id, const hssize_t *start, const hsize_t *count, const hsize_t *stride )
Description:
This function selects a hyperslab from a simple dataspace. The stride array may be used to sub-sample the hyperslab chosen, a value of 1 in each position of the stride array selects contiguous elements in the array, a value of 2 selects every other element, etc. If the stride parameter is set to NULL, a contiguous hyperslab is chosen. The values in the start and count arrays may be negative, to allow for selecting hyperslabs in chunked datasets which extend in arbitrary directions.
Parameters:
hid_t space_id
ID of the dataspace object to set hyperslab in.
const hssize_t *start
Pointer to array of starting location for hyperslab.
const hsize_t *count
Pointer to array of magnitude of hyperslab.
const hsize_t *stride
Pointer to array of stride of hyperslab.
Returns:
zero/negative

Name: H5Sget_hyperslab
Signature:
int H5Sget_hyperslab(hid_t space_id, hssize_t *start, hsize_t *count, hsize_t *stride )
Description:
This function retrieves information about the hyperslab from a simple dataspace. If no hyperslab has been defined then the hyperslab is the same as the entire array.
Parameters:
hid_t space_id
ID of the dataspace object to set hyperslab in.
hssize_t *start
Pointer to array to store starting location of hyperslab.
hsize_t *count
Pointer to array to store magnitude of hyperslab.
hsize_t *stride
Pointer to array to store stride of hyperslab.
Returns:
Hyperslab dimensionality on success, negative on failure.

Name: H5Sclose
Signature:
herr_t H5Sclose(hid_t space_id )
Description:
This function releases a dataspace. Further access through the dataspace ID is illegal. Failure to release a dataspace with this call will result in resource leaks.
Parameters:
hid_t space_id
ID of dataspace to release.
Returns:
zero/negative

Group Object API Functions

A group associates names with objects and provides a mechanism which can map a name to an object. Since all objects appear in at least one group (with the possible exception of the root object) and since objects can have names in more than one group, the set of all objects in an HDF5 file is a directed graph. The internal nodes (nodes with out-degree greater than zero) must be groups while the leaf nodes (nodes with out-degree zero) are either empty groups or objects of some other type. Exactly one object in every non-empty file is the root object. The root object always has a positive in-degree because it is pointed to by the file boot block.

Every file handle returned by H5Fcreate or H5Fopen maintains an independent current working group stack, the top item of which is the current working group (the root object is the current working group if the stack is empty). The stack can be manipulated with H5Gset, H5Gpush, and H5Gpop.

An object name consists of one or more components separated from one another by slashes. If the name begins with a slash then the object is located by looking for the first component in the root object, then looking for the second component in that object, etc., until the entire name is traversed. If the name doesn't begin with a slash then the traversal begins with the current working group.

The library does not maintain the full absolute name of its current working group because (1) cycles in the graph can make the name length unbounded and (2) a group doesn't necessarily have a unique name. A more Unix-like hierarchical naming scheme can be implemented on top of the directed graph scheme by creating a ".." entry in each group that points to its single predecessor and then a getcwd function would be trivial.


Name: H5Gcreate
Signature:
herr_t H5Gset (hid_t file, const char *name, size_t size_hint)
Description:
This function creates a new empty group and gives it a name.
Parameters:
hid_t file
The file handle returned by H5Fcreate or H5Fopen.
const char *name
The absolute or relative name of the new group.
size_t size_hint
The size hint is an optional parameter that indicates the number of bytes to reserve for the names that will appear in the group. A conservative estimate could result in multiple system-level I/O requests to read the group name heap while a liberal estimate could result in a single large I/O request even when the group has just a few names. HDF5 stores each name with a null terminator.
Returns:
Returns a negative value on failure, non-negative otherwise.

Name: H5Sopen
Signature:
hid_t H5Gopen(hid_t file_id, const char *name )
Description:
This function opens an existing group for modification. When finished, call H5Gclose() to close it and release resources.
Parameters:
hid_t file_id
ID of file to open group within.
const char * name
Name of group to open.
Returns:
Valid group ID on success, negative on failure.

Name: H5Gset
Signature:
herr_t H5Gset (hid_t file, const char *name)
Description:
This function sets the current working group by modifying the top element of the current working group stack or, if the stack is empty, by pushing a new element onto the stack.
Parameters:
hid_t file
The file handle returned by H5Fcreate or H5Fopen.
const char *name
The name of the new current working group. If the name doesn't begin with a slash then it is looked up relative the the previous current working group.
Returns:
Returns a negative value on failure, non-negative otherwise.

Name: H5Gpush
Signature:
herr_t H5Gpush (hid_t file, const char *name)
Description:
This function sets the current working group by pushing a new element onto the current working group stack.
Parameters:
hid_t file
The file handle returned by H5Fcreate or H5Fopen.
const char *name
The name of the new current working group. If the name doesn't begin with a slash then it is looked up relative the the previous current working group.
Returns:
Returns a negative value on failure, non-negative otherwise.

Name: H5Gpop
Signature:
herr_t H5Gpop (hid_t file)
Description:
This function restores the previous current working group by popping an element from the current working group stack. An empty stack implies that the current working group is the root object. Attempting to pop an empty stack results in failure.
Parameters:
hid_t file
The file handle returned by H5Fcreate or H5Fopen.
Returns:
Returns a negative value on failure, non-negative otherwise.

Name: H5Gclose
Signature:
herr_t H5Gclose(hid_t group_id )
Description:
This function releases a group. Further access through the group ID is illegal. Failure to release a group with this call will result in resource leaks.
Parameters:
hid_t group_id
ID of group to release.
Returns:
zero/negative

Glossary of data-types used

Since many of the typedefs in the HDF5 API are not well-defined yet, the types below may change radically en route to a final API...

Basic Types:

Complex Types: Disk I/O Types: