From d4e41165c430440ebc886378bf4068e1b8928872 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Wed, 9 Sep 1998 13:11:31 -0500 Subject: [svn-r676] H5.api.html is superseded by RM_H5*.html family of files. (This change occured at the time of the second alpha release.) --- doc/html/H5.api.html | 4623 -------------------------------------------------- 1 file changed, 4623 deletions(-) delete mode 100644 doc/html/H5.api.html diff --git a/doc/html/H5.api.html b/doc/html/H5.api.html deleted file mode 100644 index 5f3cf78..0000000 --- a/doc/html/H5.api.html +++ /dev/null @@ -1,4623 +0,0 @@ - -HDF5 Draft API Specification - - -
-

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_plist -
    5. H5Fclose -
    - -
  3. Property list - H5P<name> - API for manipulating object property lists -
      -
    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_plist - ) -
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_plist parameter is a property list - containing additional information required for specific - methods of access, parallel I/O for example. The - paramters for access property lists 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_plist -
Property list indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_plist. Use 0 for default access properties. -
-
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_plist, - hid_t access_plist - ) -
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_plist and - access_plist parameters are property lists - 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 property lists 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_plist -
File creation property list ID, used when modifying - default file meta-data. -
hid_taccess_plist -
Property list indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_plist. Use 0 for default access properties. -
-
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_plist -
Signature: -
hid_t H5Fget_create_plist(hid_t file_id - ) -
Description: -
This function returns a property list 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 for which to get creation property list. -
-
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 -
- -
-

Property List API Functions

-

These functions manipulate property lists 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 property list ID for a copy of the default - property list of a given type. -
-
-
Property List 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 property list to create. -
-
Returns: -
Valid ID on success, negative on failure -
- -
-
-
Name: H5Pclose -
Signature: -
herr_t H5Pclose(hid_t plist_id - ) -
Description: -
This function terminates access to a property list. -
Parameters: -
-
hid_t plist_id -
Property list ID to terminate access to. -
-
Returns: -
zero/negative -
- -
-
-
Name: H5Pget_class -
Signature: -
H5P_class_t H5Pget_class(hid_t plist_id - ) -
Description: -
This function queries the class of a property list ID. -
Parameters: -
-
hid_t plist_id -
Property list ID to query. -
-
Returns: -
Property list class code on success, negative on failure -
- -
-
-
Name: H5Pcopy -
Signature: -
hid_t H5Pcopy(hid_t plist_id - ) -
Description: -
This function makes a copy of a property list ID. -
Parameters: -
-
hid_t plist_id -
Property list ID to duplicate. -
-
Returns: -
Property list ID on success, negative on failure -
- -
-
-
Name: H5Pget_version -
Signature: -
herr_t H5Pget_version(hid_t plist_id, - int * boot, - int * freelist, - int * stab, - int * shhdr - ) -
Description: -
This function queries the version information of various objects - for a file creation property list. Any pointer parameters - which are passed as NULL are not queried. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 property lists. 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 plist_id -
Property list 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 plist_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 property lists. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 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 currenly are 2, 4, 8 and 16. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 - property lists. -
Parameters: -
-
hid_t plist_id -
Property list 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 property list which can then - be used to open file. This function is available only in the - parallel HDF5 library. -
Parameters: -
-
hid_t tid -
ID of property list 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 property list. Users should call this function - again to setup the property list. -
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 property list. Users should call this function - again to setup the property list. -
-
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 plist_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 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. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 property lists. If a parameter valued is set to - NULL, that parameter is not retrieved. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 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. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 property lists. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 property lists. Valid parameter for - layout are: -
    -
    H5D_COMPACT -
    Store raw data and object header contiguously in file. - This should only be used for very small amounts of raw - data (suggested less than 1KB). -
    H5D_CONTIGUOUS -
    Store raw data seperately from object header in one - large chunk in the file. -
    H5D_CHUNKED -
    Store raw data seperately from object header in one - large chunk in the file and store chunks of the raw - data in seperate locations in the file. -
-
Parameters: -
-
hid_t plist_id -
Property list 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 plist_id, - H5D_layout_t * layout - ) -
Description: -
Queries the layout of the raw data for a dataset. - This function is only valid for dataset creation property lists. - Valid types for layout are: -
    -
    H5D_COMPACT -
    Raw data and object header stored contiguously in file. -
    H5D_CONTIGUOUS -
    Raw data stored seperately from object header in one - large chunk in the file. -
    H5D_CHUNKED -
    Raw data stored seperately from object header in - chunks in seperate locations in the file. -
-
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 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 isn't already. -
Parameters: -
-
hid_t plist_id -
Property list 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 plist_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 - property lists. -
Parameters: -
-
hid_t plist_id -
Property list 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_tplist_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 plist_id contains - either the default property lists (H5P_DEFAULT) or a plist_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 plist_id -
ID of the dataset creation property list. -
-
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 property - list for a dataset. The property list should be released with the - H5Pclose() function. -
Parameters: -
-
hid_t dataset_id -
ID of the dataset to query. -
-
Returns: -
Dataset creation property list 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_plist_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_plist_id is a dataset - transfer property list 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_plist_id -
ID of a transfer property list 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_plist_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_plist_id is a dataset - transfer property list 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_plist_id -
ID of a transfer property list 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: -
    -
    H5T_NATIVE_CHAR -
    Native character type, declare dataset array as 'char' -
    H5T_NATIVE_UCHAR -
    Native unsigned character type, declare dataset array as 'unsigned char' -
    H5T_NATIVE_SHORT -
    Native short type, declare dataset array as 'short' -
    H5T_NATIVE_USHORT -
    Native unsigned short type, declare dataset array as 'unsigned short' -
    H5T_NATIVE_INT -
    Native int type, declare dataset array as 'int' -
    H5T_NATIVE_UINT -
    Native unsigned int type, declare dataset array as 'unsigned int' -
    H5T_NATIVE_LONG -
    Native long type, declare dataset array as 'unsigned long' -
    H5T_NATIVE_ULONG -
    Native unsigned long type, declare dataset array as 'unsigned long' -
    H5T_NATIVE_LLONG -
    Native long long type, declare dataset array as 'unsigned long long' -
    H5T_NATIVE_ULLONG -
    Native unsigned long long type, declare dataset array as 'unsigned long long' -
    H5T_NATIVE_INT8 -
    Native signed 8-bit type, declare dataset array as 'int8' -
    H5T_NATIVE_UINT8 -
    Native unsigned 8-bit type, declare dataset array as 'uint8' -
    H5T_NATIVE_INT16 -
    Native signed 16-bit type, declare dataset array as 'int16' -
    H5T_NATIVE_UINT16 -
    Native unsigned 16-bit type, declare dataset array as 'uint16' -
    H5T_NATIVE_INT32 -
    Native signed 32-bit type, declare dataset array as 'int32' -
    H5T_NATIVE_UINT32 -
    Native unsigned 32-bit type, declare dataset array as 'uint32' -
    H5T_NATIVE_INT64 -
    Native signed 64-bit type, declare dataset array as 'uint64' -
    H5T_NATIVE_UINT64 -
    Native unsigned 64-bit type, declare dataset array as 'uint64' -
    H5T_NATIVE_FLOAT -
    Native single-precision float type, declare dataset array as 'float' -
    H5T_NATIVE_DOUBLE -
    Native double-precision float type, declare dataset array as 'double' -
-
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: -
    -
    H5T_ORDER_LE -
    Little-endian byte ordering (default) -
    H5T_ORDER_BE -
    Big-endian byte ordering -
    H5T_ORDER_Vax -
    VAX-endianness byte ordering (not currently supported) -
-
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 PositionBig-Endian Offset=0Big-Endian Offset=16Little-Endian Offset=0Little-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 PositionBig-Endian Offset=0Big-Endian Offset=16Little-Endian Offset=0Little-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: -
    -
    H5T_PAD_ZERO -
    Set background to zeros. -
    H5T_PAD_ONE -
    Set background to ones. -
    H5T_PAD_BACKGROUND -
    Leave background alone. -
-
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. -
    -
    H5T_PAD_ZERO -
    Set background to zeros. -
    H5T_PAD_ONE -
    Set background to ones. -
    H5T_PAD_BACKGROUND -
    Leave background alone. -
-
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: -
    -
    H5T_SGN_NONE -
    Unsigned integer type. -
    H5T_SGN_2 -
    Two's complement signed integer type. -
-
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. -
    -
    H5T_SGN_NONE -
    Unsigned integer type. -
    H5T_SGN_2 -
    Two's complement signed 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: -
    -
    H5T_NORM_IMPLIED -
    MSB of mantissa isn't stored, always 1 -
    H5T_NORM_MSBSET -
    MSB of mantissa is always 1 -
    H5T_NORM_NONE -
    Mantissa is not normalized -
-
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: -
    -
    H5T_NORM_IMPLIED -
    MSB of mantissa isn't stored, always 1 -
    H5T_NORM_MSBSET -
    MSB of mantissa is always 1 -
    H5T_NORM_NONE -
    Mantissa is not normalized -
-
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: -
    -
    H5T_PAD_ZERO -
    Set background to zeros. -
    H5T_PAD_ONE -
    Set background to ones. -
    H5T_PAD_BACKGROUND -
    Leave background alone. -
-
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: -
    -
    H5T_PAD_ZERO -
    Set background to zeros. -
    H5T_PAD_ONE -
    Set background to ones. -
    H5T_PAD_BACKGROUND -
    Leave background alone. -
-
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: -
    -
    H5T_CSET_ASCII -
    Character set is US ASCII -
-
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: -
    -
    H5T_CSET_ASCII -
    Character set is US ASCII -
-
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: -
    -
    H5T_STR_NULL -
    Pad with zeros (as C does) -
    H5T_STR_SPACE -
    Pad with spaces (as FORTRAN does) -
-
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: -
    -
    H5T_STR_NULL -
    Pad with zeros (as C does) -
    H5T_STR_SPACE -
    Pad with spaces (as FORTRAN does) -
-
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: - - -- cgit v0.12