From 478ed94629adade57dc51bab63b2d7b03b8e7e3c Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Fri, 3 Oct 2003 15:07:00 -0500 Subject: [svn-r7536] Purpose: Alphabetized RM function entries Platforms tested: Safari, IE 5 --- doc/html/RM_H5.html | 380 +- doc/html/RM_H5D.html | 845 +++-- doc/html/RM_H5E.html | 227 +- doc/html/RM_H5F.html | 362 +- doc/html/RM_H5G.html | 1151 +++--- doc/html/RM_H5I.html | 119 +- doc/html/RM_H5P.html | 9972 +++++++++++++++++++++++++------------------------- doc/html/RM_H5R.html | 97 +- doc/html/RM_H5S.html | 933 +++-- doc/html/RM_H5T.html | 2735 +++++++------- doc/html/RM_H5Z.html | 72 +- 11 files changed, 8498 insertions(+), 8395 deletions(-) diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html index 8a088fa..2c770e7 100644 --- a/doc/html/RM_H5.html +++ b/doc/html/RM_H5.html @@ -60,8 +60,7 @@ And in this document, the -
-
+

H5: General Library Functions

@@ -163,31 +162,97 @@ facilitate moving easily between them. - +
-
Name: H5open +
Name: H5check_version
Signature: -
herr_t H5open(void) +
herr_t H5check_version(unsigned majnum, + unsigned minnum, + unsigned relnum + )
Purpose: -
Initializes the HDF5 library. +
Verifies that library versions are consistent.
Description: -
H5open initialize the library. This function is - normally called automatically, but if you find that an - HDF5 library function is failing inexplicably, try calling - this function first. +
H5check_version verifies that the arguments provided + with the function call match the version numbers compiled into + the library. +

+ H5check_version serves two slightly differing purposes. +

+ First, the function is intended to be called by the user to verify + that the version of the header files compiled into an application + matches the version of the HDF5 library being used. + One may look at the H5check definition in the file + H5public.h as an example. +

+ Due to the risks of data corruption or segmentation faults, + H5check_version causes the application to abort if the + version numbers do not match. + The abort is achieved by means of a call to the + standard C function abort(). +

+ Note that H5check_version verifies only the + major and minor version numbers and the release number; + it does not verify the sub-release value as that should be + an empty string for any official release. + This means that any two incompatible library versions must + have different {major,minor,release} numbers. (Notice the + reverse is not necessarily true.) +

+ Secondarily, H5check_version verifies that the + library version identifiers H5_VERS_MAJOR, + H5_VERS_MINOR, H5_VERS_RELEASE, + H5_VERS_SUBRELEASE, and H5_VERS_INFO + are consistent. + This is designed to catch source code inconsistencies, + but does not generate the fatal error as in the first stage + because this inconsistency does not cause errors in the data files. + If this check reveals inconsistencies, the library issues a warning + but the function does not fail. +

Parameters:
-
None. +
unsigned majnum +
IN: The major version of the library. +
unsigned minnum +
IN: The minor version of the library. +
unsigned relnum +
IN: The release number of the library.
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. +
Returns a non-negative value if successful. + Upon failure, this function causes the application to abort.
Non-C API(s): -
- - - +
- +
-
Name: H5set_free_list_limits +
Name: H5dont_atexit
Signature: -
herr_t H5set_free_list_limits(int reg_global_lim, - int reg_list_lim, - int arr_global_lim, - int arr_list_lim, - int blk_global_lim, - int blk_list_lim - ) +
herr_t H5dont_atexit(void)
Purpose: -
Sets free-list size limits. +
Instructs library not to install atexit cleanup routine.
Description: -
H5set_free_list_limits sets size limits - on all types of free lists. - The HDF5 library uses free lists internally to manage memory. - There are three types of free lists: -
  • Regular - free lists manage a single data structure. -
  • Array - free lists manage arrays of a data structure. -
  • Block - free lists manage blocks of bytes. -
- Alternate phrasing?: -
  • Regular - free lists manage data structures containing atomic data. -
  • Array - free lists manage data structures containing array data. -
  • Block - free lists manage blocks of bytes. -
-

- These are global limits, but each limit applies only to - free lists of the specified type. - Therefore, if an application sets a 1Mb limit on each of - the global lists, up to 3Mb of total storage might be - allocated, 1Mb for each of the regular, array, and - block type lists. -

- Using a value of -1 for a limit means that - no limit is set for the specified type of free list. +

H5dont_atexit indicates to the library that an + atexit() cleanup routine should not be installed. + The major 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 + called. 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:
-
int reg_global_lim -
IN: The limit on all regular free list memory used -
int reg_list_lim -
IN: The limit on memory used in each regular free list -
int arr_global_lim -
IN: The limit on all array free list memory used -
int arr_list_lim -
IN: The limit on memory used in each array free list -
int blk_global_lim -
IN: The limit on all block free list memory used -
int blk_list_lim -
IN: The limit on memory used in each block free list +
None.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- @@ -338,37 +370,35 @@ facilitate moving easily between them.
- +
-
Name: H5dont_atexit +
Name: H5get_libversion
Signature: -
herr_t H5dont_atexit(void) +
herr_t H5get_libversion(unsigned *majnum, + unsigned *minnum, + unsigned *relnum + )
Purpose: -
Instructs library not to install atexit cleanup routine. +
Returns the HDF library release number.
Description: -
H5dont_atexit indicates to the library that an - atexit() cleanup routine should not be installed. - The major 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 - called. 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). +

H5get_libversion retrieves the major, minor, and release + numbers of the version of the HDF library which is linked to + the application.
Parameters:
-
None. +
unsigned *majnum +
OUT: The major version of the library. +
unsigned *minnum +
OUT: The minor version of the library. +
unsigned *relnum +
OUT: The release number of the library.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- +
-
Name: H5get_libversion +
Name: H5open
Signature: -
herr_t H5get_libversion(unsigned *majnum, - unsigned *minnum, - unsigned *relnum - ) +
herr_t H5open(void)
Purpose: -
Returns the HDF library release number. +
Initializes the HDF5 library.
Description: -
H5get_libversion retrieves the major, minor, and release - numbers of the version of the HDF library which is linked to - the application. +
H5open initialize the library. This function is + normally called automatically, but if you find that an + HDF5 library function is failing inexplicably, try calling + this function first.
Parameters:
-
unsigned *majnum -
OUT: The major version of the library. -
unsigned *minnum -
OUT: The minor version of the library. -
unsigned *relnum -
OUT: The release number of the library. +
None.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
+
+ + + - +
-
Name: H5check_version +
Name: H5set_free_list_limits
Signature: -
herr_t H5check_version(unsigned majnum, - unsigned minnum, - unsigned relnum - ) +
herr_t H5set_free_list_limits(int reg_global_lim, + int reg_list_lim, + int arr_global_lim, + int arr_list_lim, + int blk_global_lim, + int blk_list_lim + )
Purpose: -
Verifies that library versions are consistent. +
Sets free-list size limits.
Description: -
H5check_version verifies that the arguments provided - with the function call match the version numbers compiled into - the library. -

- H5check_version serves two slightly differing purposes. -

- First, the function is intended to be called by the user to verify - that the version of the header files compiled into an application - matches the version of the HDF5 library being used. - One may look at the H5check definition in the file - H5public.h as an example. -

- Due to the risks of data corruption or segmentation faults, - H5check_version causes the application to abort if the - version numbers do not match. - The abort is achieved by means of a call to the - standard C function abort(). -

- Note that H5check_version verifies only the - major and minor version numbers and the release number; - it does not verify the sub-release value as that should be - an empty string for any official release. - This means that any two incompatible library versions must - have different {major,minor,release} numbers. (Notice the - reverse is not necessarily true.) -

- Secondarily, H5check_version verifies that the - library version identifiers H5_VERS_MAJOR, - H5_VERS_MINOR, H5_VERS_RELEASE, - H5_VERS_SUBRELEASE, and H5_VERS_INFO - are consistent. - This is designed to catch source code inconsistencies, - but does not generate the fatal error as in the first stage - because this inconsistency does not cause errors in the data files. - If this check reveals inconsistencies, the library issues a warning - but the function does not fail. - +

H5set_free_list_limits sets size limits + on all types of free lists. + The HDF5 library uses free lists internally to manage memory. + There are three types of free lists: +
  • Regular + free lists manage a single data structure. +
  • Array + free lists manage arrays of a data structure. +
  • Block + free lists manage blocks of bytes. +
+ Alternate phrasing?: +
  • Regular + free lists manage data structures containing atomic data. +
  • Array + free lists manage data structures containing array data. +
  • Block + free lists manage blocks of bytes. +
+

+ These are global limits, but each limit applies only to + free lists of the specified type. + Therefore, if an application sets a 1Mb limit on each of + the global lists, up to 3Mb of total storage might be + allocated, 1Mb for each of the regular, array, and + block type lists. +

+ Using a value of -1 for a limit means that + no limit is set for the specified type of free list.

Parameters:
-
unsigned majnum -
IN: The major version of the library. -
unsigned minnum -
IN: The minor version of the library. -
unsigned relnum -
IN: The release number of the library. +
int reg_global_lim +
IN: The limit on all regular free list memory used +
int reg_list_lim +
IN: The limit on memory used in each regular free list +
int arr_global_lim +
IN: The limit on all array free list memory used +
int arr_list_lim +
IN: The limit on memory used in each array free list +
int blk_global_lim +
IN: The limit on all block free list memory used +
int blk_list_lim +
IN: The limit on memory used in each block free list
Returns: -
Returns a non-negative value if successful. - Upon failure, this function causes the application to abort. +
Returns a non-negative value if successful; + otherwise returns a negative value.
Non-C API(s): -
- @@ -545,14 +544,13 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003
diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html index c219cb3..0d30cc7 100644 --- a/doc/html/RM_H5D.html +++ b/doc/html/RM_H5D.html @@ -61,8 +61,7 @@ And in this document, the -
-
+

H5D: Datasets Interface

@@ -200,6 +199,38 @@ facilitate moving easily between them. + +
+
+
Name: H5Dclose +
Signature: +
herr_t H5Dclose(hid_t dataset_id + ) +
Purpose: +
Closes the specified dataset. +
Description: +
H5Dclose ends access to a dataset specified by + dataset_id and releases resources used by it. + Further use of the dataset identifier is illegal in calls to + the dataset API. +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to close access to. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+ +
@@ -304,33 +335,153 @@ facilitate moving easily between them.
- +
-
Name: H5Dopen +
Name: H5Dextend
Signature: -
hid_t H5Dopen(hid_t loc_id, - const char *name +
herr_t H5Dextend(hid_t dataset_id, + const hsize_t * size )
Purpose: -
Opens an existing dataset. +
Extends a dataset with unlimited dimension.
Description: -
H5Dopen opens an existing dataset for access in the file - or group specified in loc_id. name is - a dataset name and is used to identify the dataset in the file. +
H5Dextend verifies that the dataset is at least of size + size. + The dimensionality of size is the same as that of + the dataspace of the dataset being changed. + This function cannot be applied to a dataset with fixed dimensions. +

+ Space on disk is immediately allocated for the new dataset extent + if the dataset's space allocation time is set to + H5D_ALLOC_TIME_EARLY. + Fill values will be written to the dataset if the dataset's fill time + is set to H5D_FILL_TIME_IFSET or + H5D_FILL_TIME_ALLOC. + (Also see + H5Pset_fill_time + and + H5Pset_alloc_time.) +

Parameters:
-
hid_t loc_id -
IN: Identifier of the file or group - within which the dataset to be accessed will be found. -
const char * name -
IN: The name of the dataset to access. +
hid_t dataset_id +
IN: Identifier of the dataset. +
const hsize_t * size +
IN: Array containing the new magnitude of each dimension.
Returns: -
Returns a dataset identifier if successful; +
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
+ +
+ + + +
+
+
Name: H5Dfill +
Signature: +
herr_t H5Dfill( + const void *fill, + hid_t fill_type_id, + void *buf, + hid_t buf_type_id, + hid_t space_id + ) +
Purpose: +
Fills dataspace elements with a fill value in a memory buffer. +
Description: +
H5Dfill explicitly fills + the dataspace selection in memory, space_id, + with the fill value specified in fill. + If fill is NULL, + a fill value of 0 (zero) is used. +

+ fill_type_id specifies the datatype + of the fill value.
+ buf specifies the buffer in which + the dataspace elements will be written.
+ buf_type_id specifies the datatype of + those data elements. +

+ Note that if the fill value datatype differs + from the memory buffer datatype, the fill value + will be converted to the memory buffer datatype + before filling the selection. +

Note: +
Applications sometimes write data only to portions of + an allocated dataset. It is often useful in such cases + to fill the unused space with a known + fill value. + See H5Pset_fill_value + for further discussion. + Other related functions include + H5Pget_fill_value, + H5Pfill_value_defined, + H5Pset_fill_time, + H5Pget_fill_time, + and + H5Dcreate. +
Parameters: +
+
const void *fill +
IN: Pointer to the fill value to be used. +
hid_t fill_type_id +
IN: Fill value datatype identifier. +
void *buf +
IN/OUT: Pointer to the memory buffer containing the + selection to be filled. +
hid_t buf_type_id +
IN: Datatype of dataspace elements to be filled. +
hid_t space_id +
IN: Dataspace describing memory buffer and + containing the selection to be filled. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+ + + +
+
+
Name: H5Dget_create_plist +
Signature: +
hid_t H5Dget_create_plist(hid_t dataset_id + ) +
Purpose: +
Returns an identifier for a copy of the + dataset creation property list for a dataset. +
Description: +
H5Dget_create_plist returns an identifier for a + copy of the dataset creation property list for a dataset. + The creation property list identifier should be released with + the H5Pclose function. +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to query. +
+
Returns: +
Returns a dataset creation property list identifier if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+
+
Name: H5Dget_offset +
Signature: +
haddr_t H5Dget_offset(hid_t dset_id) +
Purpose: +
Returns dataset address in file. +
Description: +
H5Dget_offset returns the address in the file + of the dataset dset_id. + That address is expressed as the offset in bytes from + the beginning of the file. +
Parameters: +
+
hid_t dset_id +
Dataset identifier. +
+
Returns: +
Returns the offset in bytes; + otherwise returns HADDR_UNDEF, a negative value. + +
+ +
@@ -424,6 +607,40 @@ facilitate moving easily between them.
+ +
+
+
Name: H5Dget_storage_size +
Signature: +
hsize_t H5Dget_storage_size(hid_t dataset_id + ) +
Purpose: +
Returns the amount of storage required for a dataset. +
Description: +
H5Dget_storage_size returns the amount of storage + that is required for the specified dataset, dataset_id. + For chunked datasets, this is the number of allocated chunks times + the chunk size. + The return value may be zero if no data has been stored. +
Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to query. +
+
Returns: +
Returns the amount of storage space allocated for the dataset, + not counting meta data; + otherwise returns 0 (zero). +
Non-C API(s): +
+ +
+ +
@@ -460,63 +677,56 @@ facilitate moving easily between them.
- +
-
Name: H5Dget_create_plist +
Name: H5Diterate
Signature: -
hid_t H5Dget_create_plist(hid_t dataset_id - ) -
Purpose: -
Returns an identifier for a copy of the - dataset creation property list for a dataset. -
Description: -
H5Dget_create_plist returns an identifier for a - copy of the dataset creation property list for a dataset. - The creation property list identifier should be released with - the H5Pclose function. -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to query. -
-
Returns: -
Returns a dataset creation property list identifier if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - - -
-
-
Name: H5Dget_offset -
Signature: -
haddr_t H5Dget_offset(hid_t dset_id) +
herr_t H5Diterate( + void *buf, + hid_t type_id, + hid_t space_id, + H5D_operator_t operator, + void *operator_data + )
Purpose: -
Returns dataset address in file. +
Iterates over all selected elements in a dataspace.
Description: -
H5Dget_offset returns the address in the file - of the dataset dset_id. - That address is expressed as the offset in bytes from - the beginning of the file. +
H5Diterate iterates over all the elements selected + in a memory buffer. The callback function is called once for each + element selected in the dataspace. +

+ The selection in the dataspace is modified so that any elements + already iterated over are removed from the selection if the + iteration is interrupted (by the H5D_operator_t + function returning non-zero) before the iteration is complete; + the iteration may then be re-started by the user where it left off. +

Parameters:
-
hid_t dset_id -
Dataset identifier. +
void *buf +
IN/OUT: Pointer to the buffer in memory containing the + elements to iterate over. +
hid_t type_id +
IN: Datatype identifier for the elements stored in + buf. +
hid_t space_id +
IN: Dataspace identifier for buf. + Also contains the selection to iterate over. +
H5D_operator_t operator +
IN: Function pointer to the routine to be called + for each element in buf iterated over. +
void *operator_data +
IN/OUT: Pointer to any user-defined data associated + with the operation.
Returns: -
Returns the offset in bytes; - otherwise returns HADDR_UNDEF, a negative value. +
Returns the return value of the last operator if it was non-zero, + or zero if all elements have been processed. + Otherwise returns a negative value. - -
-
-
Name: H5Dget_storage_size -
Signature: -
hsize_t H5Dget_storage_size(hid_t dataset_id - ) -
Purpose: -
Returns the amount of storage required for a dataset. -
Description: -
H5Dget_storage_size returns the amount of storage - that is required for the specified dataset, dataset_id. - For chunked datasets, this is the number of allocated chunks times - the chunk size. - The return value may be zero if no data has been stored. -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to query. -
-
Returns: -
Returns the amount of storage space allocated for the dataset, - not counting meta data; - otherwise returns 0 (zero). -
Non-C API(s): -
- -
- - - -
-
-
Name: H5Dvlen_get_buf_size -
Signature: -
herr_t H5Dvlen_get_buf_size(hid_t dataset_id, - hid_t type_id, - hid_t space_id, - hsize_t *size - ) -
Purpose: -
Determines the number of bytes required to store VL data. -
Description: -
H5Dvlen_get_buf_size determines the number of bytes - required to store the VL data from the dataset, using the - space_id for the selection in the dataset on - disk and the type_id for the memory representation - of the VL data in memory. -

- *size is returned with the number of bytes - required to store the VL data in memory. -

Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to query. -
hid_t type_id -
IN: Datatype identifier. -
hid_t space_id -
IN: Dataspace identifier. -
hsize_t *size -
OUT: The size in bytes of the memory buffer required to store the VL data. -
-
Returns: -
Returns non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
There is no direct FORTRAN couterpart for the C function - H5Dvlen_get_buf_size; - corresponding functionality is provided by the FORTRAN function - h5dvlen_get_max_len_f. -
- - -
- - - +
-
Name: H5Dvlen_reclaim +
Name: H5Dopen
Signature: -
herr_t H5Dvlen_reclaim(hid_t type_id, - hid_t space_id, - hid_t plist_id, - void *buf +
hid_t H5Dopen(hid_t loc_id, + const char *name )
Purpose: -
Reclaims VL datatype memory buffers. +
Opens an existing dataset.
Description: -
H5Dvlen_reclaim reclaims memory buffers created to - store VL datatypes. -

- The type_id must be the datatype stored in the buffer. - The space_id describes the selection for the memory buffer - to free the VL datatypes within. - The plist_id is the dataset transfer property list which - was used for the I/O transfer to create the buffer. - And buf is the pointer to the buffer to be reclaimed. -

- The VL structures (hvl_t) in the user's buffer are - modified to zero out the VL information after the memory has been reclaimed. -

- If nested VL datatypes were used to create the buffer, - this routine frees them from the bottom up, releasing all - the memory without creating memory leaks. +

H5Dopen opens an existing dataset for access in the file + or group specified in loc_id. name is + a dataset name and is used to identify the dataset in the file.
Parameters:
-
hid_t type_id -
IN: Identifier of the datatype. -
hid_t space_id -
IN: Identifier of the dataspace. -
hid_t plist_id -
IN: Identifier of the property list used to create the buffer. -
void *buf -
IN: Pointer to the buffer to be reclaimed. +
hid_t loc_id +
IN: Identifier of the file or group + within which the dataset to be accessed will be found. +
const char * name +
IN: The name of the dataset to access.
Returns: -
Returns non-negative value if successful; +
Returns a dataset identifier if successful; otherwise returns a negative value. - @@ -797,43 +903,147 @@ facilitate moving easily between them. xfer_plist_id can be the constant H5P_DEFAULT. in which case the default data transfer properties are used.

- Data is automatically converted from the file datatype - and dataspace to the memory datatype and dataspace - at the time of the read. See the - Data Conversion - section of The Data Type Interface (H5T) in the - HDF5 User's Guide for a discussion of - data conversion, including the range of conversions currently - supported by the HDF5 libraries. + Data is automatically converted from the file datatype + and dataspace to the memory datatype and dataspace + at the time of the read. See the + Data Conversion + section of The Data Type Interface (H5T) in the + HDF5 User's Guide for a discussion of + data conversion, including the range of conversions currently + supported by the HDF5 libraries. +

Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset read from. +
hid_t mem_type_id +
IN: Identifier of the memory datatype. +
hid_t mem_space_id +
IN: Identifier of the memory dataspace. +
hid_t file_space_id +
IN: Identifier of the dataset's dataspace in the file. +
hid_t xfer_plist_id +
IN: Identifier of a transfer property list + for this I/O operation. +
void * buf +
OUT: Buffer to receive data read from file. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+ + + +
+
+
Name: H5Dvlen_get_buf_size +
Signature: +
herr_t H5Dvlen_get_buf_size(hid_t dataset_id, + hid_t type_id, + hid_t space_id, + hsize_t *size + ) +
Purpose: +
Determines the number of bytes required to store VL data. +
Description: +
H5Dvlen_get_buf_size determines the number of bytes + required to store the VL data from the dataset, using the + space_id for the selection in the dataset on + disk and the type_id for the memory representation + of the VL data in memory. +

+ *size is returned with the number of bytes + required to store the VL data in memory. +

Parameters: +
+
hid_t dataset_id +
IN: Identifier of the dataset to query. +
hid_t type_id +
IN: Datatype identifier. +
hid_t space_id +
IN: Dataspace identifier. +
hsize_t *size +
OUT: The size in bytes of the memory buffer required to store the VL data. +
+
Returns: +
Returns non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
There is no direct FORTRAN couterpart for the C function + H5Dvlen_get_buf_size; + corresponding functionality is provided by the FORTRAN function + h5dvlen_get_max_len_f. +
+ + +
+ + + +
+
+
Name: H5Dvlen_reclaim +
Signature: +
herr_t H5Dvlen_reclaim(hid_t type_id, + hid_t space_id, + hid_t plist_id, + void *buf + ) +
Purpose: +
Reclaims VL datatype memory buffers. +
Description: +
H5Dvlen_reclaim reclaims memory buffers created to + store VL datatypes. +

+ The type_id must be the datatype stored in the buffer. + The space_id describes the selection for the memory buffer + to free the VL datatypes within. + The plist_id is the dataset transfer property list which + was used for the I/O transfer to create the buffer. + And buf is the pointer to the buffer to be reclaimed. +

+ The VL structures (hvl_t) in the user's buffer are + modified to zero out the VL information after the memory has been reclaimed. +

+ If nested VL datatypes were used to create the buffer, + this routine frees them from the bottom up, releasing all + the memory without creating memory leaks.

Parameters:
-
hid_t dataset_id -
IN: Identifier of the dataset read from. -
hid_t mem_type_id -
IN: Identifier of the memory datatype. -
hid_t mem_space_id -
IN: Identifier of the memory dataspace. -
hid_t file_space_id -
IN: Identifier of the dataset's dataspace in the file. -
hid_t xfer_plist_id -
IN: Identifier of a transfer property list - for this I/O operation. -
void * buf -
OUT: Buffer to receive data read from file. +
hid_t type_id +
IN: Identifier of the datatype. +
hid_t space_id +
IN: Identifier of the dataspace. +
hid_t plist_id +
IN: Identifier of the property list used to create the buffer. +
void *buf +
IN: Pointer to the buffer to be reclaimed.
Returns: -
Returns a non-negative value if successful; +
Returns non-negative value if successful; otherwise returns a negative value. +
-
@@ -1016,219 +1226,6 @@ facilitate moving easily between them. -->
- - -
-
-
Name: H5Dextend -
Signature: -
herr_t H5Dextend(hid_t dataset_id, - const hsize_t * size - ) -
Purpose: -
Extends a dataset with unlimited dimension. -
Description: -
H5Dextend verifies that the dataset is at least of size - size. - The dimensionality of size is the same as that of - the dataspace of the dataset being changed. - This function cannot be applied to a dataset with fixed dimensions. -

- Space on disk is immediately allocated for the new dataset extent - if the dataset's space allocation time is set to - H5D_ALLOC_TIME_EARLY. - Fill values will be written to the dataset if the dataset's fill time - is set to H5D_FILL_TIME_IFSET or - H5D_FILL_TIME_ALLOC. - (Also see - H5Pset_fill_time - and - H5Pset_alloc_time.) - -

Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset. -
const hsize_t * size -
IN: Array containing the new magnitude of each dimension. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - - -
-
-
Name: H5Dclose -
Signature: -
herr_t H5Dclose(hid_t dataset_id - ) -
Purpose: -
Closes the specified dataset. -
Description: -
H5Dclose ends access to a dataset specified by - dataset_id and releases resources used by it. - Further use of the dataset identifier is illegal in calls to - the dataset API. -
Parameters: -
-
hid_t dataset_id -
IN: Identifier of the dataset to close access to. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- - - -
-
-
Name: H5Diterate -
Signature: -
herr_t H5Diterate( - void *buf, - hid_t type_id, - hid_t space_id, - H5D_operator_t operator, - void *operator_data - ) -
Purpose: -
Iterates over all selected elements in a dataspace. -
Description: -
H5Diterate iterates over all the elements selected - in a memory buffer. The callback function is called once for each - element selected in the dataspace. -

- The selection in the dataspace is modified so that any elements - already iterated over are removed from the selection if the - iteration is interrupted (by the H5D_operator_t - function returning non-zero) before the iteration is complete; - the iteration may then be re-started by the user where it left off. - -

Parameters: -
-
void *buf -
IN/OUT: Pointer to the buffer in memory containing the - elements to iterate over. -
hid_t type_id -
IN: Datatype identifier for the elements stored in - buf. -
hid_t space_id -
IN: Dataspace identifier for buf. - Also contains the selection to iterate over. -
H5D_operator_t operator -
IN: Function pointer to the routine to be called - for each element in buf iterated over. -
void *operator_data -
IN/OUT: Pointer to any user-defined data associated - with the operation. -
-
Returns: -
Returns the return value of the last operator if it was non-zero, - or zero if all elements have been processed. - Otherwise returns a negative value. - -
- - - -
-
-
Name: H5Dfill -
Signature: -
herr_t H5Dfill( - const void *fill, - hid_t fill_type_id, - void *buf, - hid_t buf_type_id, - hid_t space_id - ) -
Purpose: -
Fills dataspace elements with a fill value in a memory buffer. -
Description: -
H5Dfill explicitly fills - the dataspace selection in memory, space_id, - with the fill value specified in fill. - If fill is NULL, - a fill value of 0 (zero) is used. -

- fill_type_id specifies the datatype - of the fill value.
- buf specifies the buffer in which - the dataspace elements will be written.
- buf_type_id specifies the datatype of - those data elements. -

- Note that if the fill value datatype differs - from the memory buffer datatype, the fill value - will be converted to the memory buffer datatype - before filling the selection. -

Note: -
Applications sometimes write data only to portions of - an allocated dataset. It is often useful in such cases - to fill the unused space with a known - fill value. - See H5Pset_fill_value - for further discussion. - Other related functions include - H5Pget_fill_value, - H5Pfill_value_defined, - H5Pset_fill_time, - H5Pget_fill_time, - and - H5Dcreate. -
Parameters: -
-
const void *fill -
IN: Pointer to the fill value to be used. -
hid_t fill_type_id -
IN: Fill value datatype identifier. -
void *buf -
IN/OUT: Pointer to the memory buffer containing the - selection to be filled. -
hid_t buf_type_id -
IN: Datatype of dataspace elements to be filled. -
hid_t space_id -
IN: Dataspace describing memory buffer and - containing the selection to be filled. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- -
- -
@@ -1262,17 +1259,15 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003
- diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html index 64e9977..e5fa126 100644 --- a/doc/html/RM_H5E.html +++ b/doc/html/RM_H5E.html @@ -61,8 +61,7 @@ And in this document, the
-
-
+

H5E: Error Interface

@@ -194,42 +193,31 @@ errors within the H5E package. - +
-
Name: H5Eset_auto +
Name: H5Eclear
Signature: -
herr_t H5Eset_auto(H5E_auto_t func, - void *client_data - ) +
herr_t H5Eclear(void)
Purpose: -
Turns automatic error printing on or off. +
Clears the error stack for the current thread.
Description: -
H5Eset_auto turns on or off automatic printing of - errors. When turned on (non-null func pointer), - any API function which returns an error indication will - first call func, passing it client_data - as an argument. +
H5Eclear clears the error stack for the current thread.

- When the library is first initialized the auto printing function - is set to H5Eprint (cast appropriately) and - client_data is the standard error stream pointer, - stderr. + The stack is also cleared whenever an API function is called, + with certain exceptions (for instance, H5Eprint).

- Automatic stack traversal is always in the - H5E_WALK_DOWNWARD direction. + H5Eclear can fail if there are problems initializing + the library.

Parameters:
-
H5E_auto_t func -
IN: Function to be called upon an error condition. -
void *client_data -
IN: Data passed to the error function. +
None
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- +
-
Name: H5Eclear +
Name: H5Eget_major
Signature: -
herr_t H5Eclear(void) +
const char * H5Eget_major(H5E_major_t n)
Purpose: -
Clears the error stack for the current thread. +
Returns a character string describing an error specified by a + major error number.
Description: -
H5Eclear clears the error stack for the current thread. -

- The stack is also cleared whenever an API function is called, - with certain exceptions (for instance, H5Eprint). +

Given a major error number, H5Eget_major returns a + constant character string that describes the error. +
Parameters: +
+
H5E_major_t n +
IN: Major error number. +
+
Returns: +
Returns a character string describing the error if successful. + Otherwise returns "Invalid major error number." +
Non-C API(s): +
+ +
+ + + +
+
+
Name: H5Eget_minor +
Signature: +
const char * H5Eget_minor(H5E_minor_t n) +
Purpose: +
Returns a character string describing an error specified by a + minor error number. +
Description: +
Given a minor error number, H5Eget_minor returns a + constant character string that describes the error. +
Parameters: +
+
H5E_minor_t n +
IN: Minor error number. +
+
Returns: +
Returns a character string describing the error if successful. + Otherwise returns "Invalid minor error number." +
Non-C API(s): +
+ +
+ + + +
+
+
Name: H5Eprint +
Signature: +
herr_t H5Eprint(FILE * stream) +
Purpose: +
Prints the error stack in a default manner. +
Description: +
H5Eprint prints the error stack on the specified + stream, stream. + Even if the error stack is empty, a one-line message will be printed: +
     + HDF5-DIAG: Error detected in thread 0.

- H5Eclear can fail if there are problems initializing - the library. + H5Eprint is a convenience function for + H5Ewalk with a function that prints error messages. + Users are encouraged to write their own more specific error handlers.

Parameters:
-
None +
FILE * stream +
IN: File pointer, or stderr if NULL.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- +
-
Name: H5Eprint +
Name: H5Eset_auto
Signature: -
herr_t H5Eprint(FILE * stream) +
herr_t H5Eset_auto(H5E_auto_t func, + void *client_data + )
Purpose: -
Prints the error stack in a default manner. +
Turns automatic error printing on or off.
Description: -
H5Eprint prints the error stack on the specified - stream, stream. - Even if the error stack is empty, a one-line message will be printed: -
     - HDF5-DIAG: Error detected in thread 0. +
H5Eset_auto turns on or off automatic printing of + errors. When turned on (non-null func pointer), + any API function which returns an error indication will + first call func, passing it client_data + as an argument.

- H5Eprint is a convenience function for - H5Ewalk with a function that prints error messages. - Users are encouraged to write their own more specific error handlers. + When the library is first initialized the auto printing function + is set to H5Eprint (cast appropriately) and + client_data is the standard error stream pointer, + stderr. +

+ Automatic stack traversal is always in the + H5E_WALK_DOWNWARD direction.

Parameters:
-
FILE * stream -
IN: File pointer, or stderr if NULL. +
H5E_auto_t func +
IN: Function to be called upon an error condition. +
void *client_data +
IN: Data passed to the error function.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- - -
-
-
Name: H5Eget_major -
Signature: -
const char * H5Eget_major(H5E_major_t n) -
Purpose: -
Returns a character string describing an error specified by a - major error number. -
Description: -
Given a major error number, H5Eget_major returns a - constant character string that describes the error. -
Parameters: -
-
H5E_major_t n -
IN: Major error number. -
-
Returns: -
Returns a character string describing the error if successful. - Otherwise returns "Invalid major error number." -
Non-C API(s): -
- -
- - - -
-
-
Name: H5Eget_minor -
Signature: -
const char * H5Eget_minor(H5E_minor_t n) -
Purpose: -
Returns a character string describing an error specified by a - minor error number. -
Description: -
Given a minor error number, H5Eget_minor returns a - constant character string that describes the error. -
Parameters: -
-
H5E_minor_t n -
IN: Minor error number. -
-
Returns: -
Returns a character string describing the error if successful. - Otherwise returns "Invalid minor error number." -
Non-C API(s): -
- -
- -
@@ -635,14 +633,13 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003
diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html index 04b0b97..c14c064 100644 --- a/doc/html/RM_H5F.html +++ b/doc/html/RM_H5F.html @@ -61,8 +61,7 @@ And in this document, the
-
-
+

H5F: File Interface

@@ -183,98 +182,63 @@ facilitate moving easily between them. - +
-
Name: H5Fopen +
Name: H5Fclose
Signature: -
hid_t H5Fopen(const char *name, - unsigned flags, - hid_t access_id +
herr_t H5Fclose(hid_t file_id )
Purpose: -
Opens an existing file. +
Terminates access to an HDF5 file.
Description: -
H5Fopen opens an existing file and is the primary - function for accessing existing HDF5 files. -

- The parameter access_id is a file access property - list identifier or H5P_DEFAULT if the - default I/O access parameters are to be used -

- The flags argument determines whether writing - to an existing file will be allowed. - The file is opened with read and write permission if - flags is set to H5F_ACC_RDWR. - All flags may be combined with the bit-wise OR operator (`|') - to change the behavior of the file open call. - More complex behaviors of file access are controlled - through the file-access property list. +

H5Fclose terminates access to an HDF5 file + by flushing all data to storage and terminating access + to the file through file_id.

- The return value is a file identifier for the open file; - this file identifier should be closed by calling - H5Fclose when it is no longer needed. + If this is the last file identifier open for the file + and no other access identifier is open (e.g., a dataset + identifier, group identifier, or shared datatype identifier), + the file will be fully closed and access will end.

- - Special case -- Multiple opens: + Delayed close:
- A file can often be opened with a new H5Fopen - call without closing an already-open identifier established - in a previous H5Fopen or H5Fcreate - call. Each such H5Fopen call will return a - unique identifier and the file can be accessed through any - of these identifiers as long as the identifier remains valid. - In such multiply-opened cases, all the open calls should - use the same flags argument. -

- In some cases, such as files on a local Unix file system, - the HDF5 library can detect that a file is multiply opened and - will maintain coherent access among the file identifiers. + Note the following deviation from the above-described behavior. + If H5Fclose is called for a file but one or more + objects within the file remain open, those objects will remain + accessible until they are individually closed. + Thus, if the dataset data_sample is open when + H5Fclose is called for the file containing it, + data_sample will remain open and accessible + (including writable) until it is explicitely closed. + The file will be automatically closed once all objects in the + file have been closed.

- But in many other cases, such as parallel file systems or - networked file systems, it is not always possible to detect - multiple opens of the same physical file. - In such cases, HDF5 will treat the file identifiers - as though they are accessing different files and - will be unable to maintain coherent access. - Errors are likely to result in these cases. - While unlikely, the HDF5 library may not be able to detect, - and thus report, such errors. + Be warned, hoever, that there are circumstances where it is + not possible to delay closing a file. + For example, an MPI-IO file close is a collective call; all of + the processes that opened the file must close it collectively. + The file cannot be closed at some time in the future by each + process in an independent fashion. + Another example is that an application using an AFS token-based + file access privilage may destroy its AFS token after + H5Fclose has returned successfully. + This would make any future access to the file, or any object + within it, illegal.

- It is generally recommended that applications avoid - multiple opens of the same file. - + In such situations, applications must close all open objects + in a file before calling H5Fclose. + It is generally recommended to do so in all cases.

Parameters:
-
const char *name -
IN: Name of the file to access. -
unsigned flags -
IN: File access flags. Allowable values are: -
    -
    H5F_ACC_RDWR -
    Allow read and write access to file. -
    H5F_ACC_RDONLY -
    Allow read-only access to file. -
    -
  • H5F_ACC_RDWR and H5F_ACC_RDONLY - are mutually exclusive; use exactly one. -
  • An additional flag, H5F_ACC_DEBUG, prints - debug information. This flag is used only by HDF5 library - developers; it is neither tested nor supported - for use in applications. -
-
hid_t access_id -
IN: Identifier for the file access properties list. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_id. - Use H5P_DEFAULT for default file access properties. +
hid_t file_id +
IN: Identifier of a file to terminate access to.
Returns: -
Returns a file identifier if successful; +
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- -
-
-
Name: H5Fis_hdf5 -
Signature: -
htri_t H5Fis_hdf5(const char *name - ) -
Purpose: -
Determines whether a file is in the HDF5 format. -
Description: -
H5Fis_hdf5 determines whether a file is in - the HDF5 format. -
Parameters: -
-
const char *name -
IN: File name to check format. -
-
Returns: -
When successful, returns a positive value, for TRUE, - or 0 (zero), for FALSE. - Otherwise returns a negative value. -
Non-C API(s): -
- -
- -
@@ -743,63 +676,29 @@ facilitate moving easily between them.
- +
-
Name: H5Fclose +
Name: H5Fis_hdf5
Signature: -
herr_t H5Fclose(hid_t file_id +
htri_t H5Fis_hdf5(const char *name )
Purpose: -
Terminates access to an HDF5 file. +
Determines whether a file is in the HDF5 format.
Description: -
H5Fclose terminates access to an HDF5 file - by flushing all data to storage and terminating access - to the file through file_id. -

- If this is the last file identifier open for the file - and no other access identifier is open (e.g., a dataset - identifier, group identifier, or shared datatype identifier), - the file will be fully closed and access will end. -

- Delayed close: -
- Note the following deviation from the above-described behavior. - If H5Fclose is called for a file but one or more - objects within the file remain open, those objects will remain - accessible until they are individually closed. - Thus, if the dataset data_sample is open when - H5Fclose is called for the file containing it, - data_sample will remain open and accessible - (including writable) until it is explicitely closed. - The file will be automatically closed once all objects in the - file have been closed. -

- Be warned, hoever, that there are circumstances where it is - not possible to delay closing a file. - For example, an MPI-IO file close is a collective call; all of - the processes that opened the file must close it collectively. - The file cannot be closed at some time in the future by each - process in an independent fashion. - Another example is that an application using an AFS token-based - file access privilage may destroy its AFS token after - H5Fclose has returned successfully. - This would make any future access to the file, or any object - within it, illegal. -

- In such situations, applications must close all open objects - in a file before calling H5Fclose. - It is generally recommended to do so in all cases. +

H5Fis_hdf5 determines whether a file is in + the HDF5 format.
Parameters:
-
hid_t file_id -
IN: Identifier of a file to terminate access to. +
const char *name +
IN: File name to check format.
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. +
When successful, returns a positive value, for TRUE, + or 0 (zero), for FALSE. + Otherwise returns a negative value.
Non-C API(s): -
- +
-
Name: H5Funmount +
Name: H5Fopen
Signature: -
herr_t H5Funmount(hid_t loc_id, - const char *name +
hid_t H5Fopen(const char *name, + unsigned flags, + hid_t access_id )
Purpose: -
Unmounts a file. +
Opens an existing file.
Description: -
Given a mount point, H5Funmount - dissassociates the mount point's file - from the file mounted there. This function - does not close either file. -

- The mount point can be either the group in the - parent or the root group of the mounted file - (both groups have the same name). If the mount - point was opened before the mount then it is the - group in the parent; if it was opened after the - mount then it is the root group of the child. +

H5Fopen opens an existing file and is the primary + function for accessing existing HDF5 files.

- Note that loc_id is either a file or group identifier - and name is relative to loc_id. + The parameter access_id is a file access property + list identifier or H5P_DEFAULT if the + default I/O access parameters are to be used +

+ The flags argument determines whether writing + to an existing file will be allowed. + The file is opened with read and write permission if + flags is set to H5F_ACC_RDWR. + All flags may be combined with the bit-wise OR operator (`|') + to change the behavior of the file open call. + More complex behaviors of file access are controlled + through the file-access property list. +

+ The return value is a file identifier for the open file; + this file identifier should be closed by calling + H5Fclose when it is no longer needed. +

+ + Special case -- Multiple opens: +
+ A file can often be opened with a new H5Fopen + call without closing an already-open identifier established + in a previous H5Fopen or H5Fcreate + call. Each such H5Fopen call will return a + unique identifier and the file can be accessed through any + of these identifiers as long as the identifier remains valid. + In such multiply-opened cases, all the open calls should + use the same flags argument. +

+ In some cases, such as files on a local Unix file system, + the HDF5 library can detect that a file is multiply opened and + will maintain coherent access among the file identifiers. +

+ But in many other cases, such as parallel file systems or + networked file systems, it is not always possible to detect + multiple opens of the same physical file. + In such cases, HDF5 will treat the file identifiers + as though they are accessing different files and + will be unable to maintain coherent access. + Errors are likely to result in these cases. + While unlikely, the HDF5 library may not be able to detect, + and thus report, such errors. +

+ It is generally recommended that applications avoid + multiple opens of the same file. +

Parameters:
-
hid_t loc_id -
IN: File or group identifier for the location at which - the specified file is to be unmounted.
const char *name -
IN: Name of the mount point. +
IN: Name of the file to access. +
unsigned flags +
IN: File access flags. Allowable values are: +
    +
    H5F_ACC_RDWR +
    Allow read and write access to file. +
    H5F_ACC_RDONLY +
    Allow read-only access to file. +
    +
  • H5F_ACC_RDWR and H5F_ACC_RDONLY + are mutually exclusive; use exactly one. +
  • An additional flag, H5F_ACC_DEBUG, prints + debug information. This flag is used only by HDF5 library + developers; it is neither tested nor supported + for use in applications. +
+
hid_t access_id +
IN: Identifier for the file access properties list. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + access_id. + Use H5P_DEFAULT for default file access properties.
Returns: -
Returns a non-negative value if successful; +
Returns a file identifier if successful; otherwise returns a negative value.
Non-C API(s): -
+ + +
+
+
Name: H5Funmount +
Signature: +
herr_t H5Funmount(hid_t loc_id, + const char *name + ) +
Purpose: +
Unmounts a file. +
Description: +
Given a mount point, H5Funmount + dissassociates the mount point's file + from the file mounted there. This function + does not close either file. +

+ The mount point can be either the group in the + parent or the root group of the mounted file + (both groups have the same name). If the mount + point was opened before the mount then it is the + group in the parent; if it was opened after the + mount then it is the root group of the child. +

+ Note that loc_id is either a file or group identifier + and name is relative to loc_id. +

Parameters: +
+
hid_t loc_id +
IN: File or group identifier for the location at which + the specified file is to be unmounted. +
const char *name +
IN: Name of the mount point. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): +
+ +
+ + +
@@ -979,14 +980,13 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003
diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html index 88cfd61..88fa534 100644 --- a/doc/html/RM_H5G.html +++ b/doc/html/RM_H5G.html @@ -61,8 +61,7 @@ And in this document, the
-
-
+

H5G: Group Interface

@@ -213,6 +212,41 @@ create or access function. + +
+
+
Name: H5Gclose +
Signature: +
herr_t H5Gclose(hid_t group_id) +
Purpose: +
Closes the specified group. +
Description: +
H5Gclose releases resources used by a group which was + opened by H5Gcreate or H5Gopen. + After closing a group, the group_id cannot be used again. +

+ Failure to release a group with this call will result in resource leaks. +

Parameters: +
+
hid_t group_id +
IN: Group identifier to release. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): + +
+ +
+ +
@@ -273,43 +307,49 @@ create or access function. -->
- - +
-
Name: H5Gopen +
Name: H5Gget_comment
Signature: -
hid_t H5Gopen(hid_t loc_id, - const char *name +
herr_t H5Gget_comment(hid_t loc_id, + const char *name, + size_t bufsize, + char *comment )
Purpose: -
Opens an existing group for modification and returns a group - identifier for that group. +
Retrieves comment for specified object.
Description: -
H5Gopen opens an existing group with the specified - name at the specified location, loc_id. +
H5Gget_comment retrieves the comment for the the + object name. The comment is returned in the buffer + comment.

- The location is identified by a file or group identifier + At most bufsize characters, including a null + terminator, are copied. The result is not null terminated + if the comment is longer than the supplied buffer.

- H5Gopen returns a group identifier for the group - that was opened. This group identifier should be released by - calling H5Gclose when it is no longer needed. + If an object does not have a comment, the empty string + is returned.

Parameters:
hid_t loc_id -
IN: File or group identifier within which group is to be open. -
const char * name -
IN: Name of group to open. +
IN: Identifier of the file or group. +
const char *name +
IN: Name of the object whose comment is to be set or reset. +
size_t bufsize +
IN: Anticipated size of the buffer required to hold + comment. +
char *comment +
OUT: The comment.
Returns: -
Returns a valid group identifier if successful; - otherwise returns a negative value. +
Returns the number of characters in the comment, + counting the null terminator, if successful; the value + returned may be larger than bufsize. + Otherwise returns a negative value.
Non-C API(s): - -
- +
-
Name: H5Gclose +
Name: H5Gget_linkval
Signature: -
herr_t H5Gclose(hid_t group_id) +
herr_t H5Gget_linkval(hid_t loc_id, + const char *name, + size_t size, + char *value + )
Purpose: -
Closes the specified group. +
Returns the name of the object that the symbolic link points to.
Description: -
H5Gclose releases resources used by a group which was - opened by H5Gcreate or H5Gopen. - After closing a group, the group_id cannot be used again. +
H5Gget_linkval returns size + characters of the name of the object that the symbolic link name points to.

- Failure to release a group with this call will result in resource leaks. + The parameter loc_id is a file or group identifier. +

+ The parameter name must be a symbolic link pointing to + the desired object and must be defined relative to loc_id. +

+ If size is smaller than the size of the returned object name, then + the name stored in the buffer value will not be null terminated. +

+ This function fails if name is not a symbolic link. + The presence of a symbolic link can be tested by passing zero for + size and NULL for value. +

+ This function should be used only after H5Gget_objinfo has been called + to verify that name is a symbolic link.

Parameters:
-
hid_t group_id -
IN: Group identifier to release. +
hid_t loc_id +
IN: Identifier of the file or group. +
const char *name +
IN: Symbolic link to the object whose name is to be returned. +
size_t size +
IN: Maximum number of characters of value + to be returned. +
char *value +
OUT: A buffer to hold the name of the object being sought.
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. +
Returns a non-negative value, with the link value in value, + if successful. + Otherwise returns a negative value.
Non-C API(s): - -
- +
-
Name: H5Glink +
Name: H5Gget_num_objs +
Signature: +
herr_t H5Gget_num_objs(hid_t loc_id, + hsize_t* num_obj) +
Purpose: +
Returns number of objects in the group specified by its identifier +
Description: +
H5Gget_num_objs returns number of objects in a group. + Group is specified by its identifier loc_id. + If file identifier is passed in, then number of objects in the + root group is returned. +
Parameters: +
+
hid_t loc_id +
IN: Identifier of the group or the file +
hsize_t* num_obj +
OUT: Number of objects in the group. +
+
Returns: +
Returns positive value if successful; + otherwise returns a negative value. +
+ + + +
+
+
Name: H5Gget_objinfo
Signature: -
herr_t H5Glink(hid_t loc_id, - H5G_link_t link_type, - const char *current_name, - const char *new_name +
herr_t H5Gget_objinfo(hid_t loc_id, + const char *name, + hbool_t follow_link, + H5G_stat_t *statbuf )
Purpose: -
Creates a link of the specified type from new_name - to current_name. +
Returns information about an object.
Description: -
H5Glink creates a new name for an object that has some current - name, possibly one of many names it currently has. +
H5Gget_objinfo returns information about the + specified object through the statbuf argument. + loc_id (a file or group identifier) and + name together determine the object. + If the object is a symbolic link and follow_link is + zero (0), then the information returned is that for the link itself; + otherwise the link is followed and information is returned about + the object to which the link points. + If follow_link is non-zero but the final symbolic link + is dangling (does not point to anything), then an error is returned. + The statbuf fields are undefined for an error. + The existence of an object can be tested by calling this function + with a null statbuf.

- If link_type is H5G_LINK_HARD, then - current_name must specify the name of an - existing object and both - names are interpreted relative to loc_id, which is - either a file identifier or a group identifier. + H5Gget_objinfo fills in the following data structure: + 

+                  typedef struct H5G_stat_t {
+                      unsigned long fileno[2];
+                      unsigned long objno[2];
+                      unsigned nlink;
+                      int type;
+                      time_t mtime; 
+                      size_t linklen;
+                  } H5G_stat_t
+
+ The fileno and objno fields contain + four values which uniquely itentify an object among those + HDF5 files which are open: if all four values are the same + between two objects, then the two objects are the same + (provided both files are still open). +
    +
  • Note that if a file is closed and re-opened, the + value in fileno will change. +
  • If a VFL driver either does not or cannot detect that + two H5Fopen calls referencing the same file + actually open the same file, each will get a different + fileno. +

- If link_type is H5G_LINK_SOFT, then - current_name can be anything and is interpreted at - lookup time relative to the group which contains the final - component of new_name. For instance, if - current_name is ./foo, - new_name is ./x/y/bar, and a request - is made for ./x/y/bar, then the actual object looked - up is ./x/y/./foo. + The nlink field is the number of hard links to + the object or zero when information is being returned about a + symbolic link (symbolic links do not have hard links but + all other objects always have at least one). + The type field contains the type of the object, + one of + H5G_GROUP, + H5G_DATASET, + H5G_LINK, or + H5G_TYPE. + The mtime field contains the modification time. + If information is being returned about a symbolic link then + linklen will be the length of the link value + (the name of the pointed-to object with the null terminator); + otherwise linklen will be zero. + Other fields may be added to this structure in the future. +

Note: +
Some systems will be able to record the time accurately but + unable to retrieve the correct time; such systems (e.g., Irix64) + will report an mtime value of 0 (zero).
Parameters:
hid_t loc_id
IN: File or group identifier. -
H5G_link_t link_type -
IN: Link type. - Possible values are H5G_LINK_HARD and - H5G_LINK_SOFT. -
const char * current_name -
IN: Name of the existing object if link is a hard link. - Can be anything for the soft link. -
const char * new_name -
IN: New name for the object. +
const char *name +
IN: Name of the object for which status is being sought. +
hbool_t follow_link +
IN: Link flag. +
H5G_stat_t *statbuf +
OUT: Buffer in which to return information about the object.
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): +
Returns a non-negative value if successful, with the fields of + statbuf (if non-null) initialized. + Otherwise returns a negative value. -
Non-C API(s): +
+--> - +
-
Name: H5Glink2 -
Signature: - -
herr_t H5Glink2( - hid_t curr_loc_id, const char *current_name, - H5G_link_t link_type, - hid_t new_loc_id, const char *new_name ) -
Purpose: -
Creates a link of the specified type from new_name - to current_name. -
Description: - -
H5Glink2 creates a new name for an object that has some current - name, possibly one of many names it currently has. -

- If link_type is H5G_LINK_HARD, then current_name - must specify the name of an existing object. - In this case, current_name and new_name are interpreted - relative to curr_loc_id and new_loc_id, respectively, - which are either file or group identifiers. -

- If link_type is H5G_LINK_SOFT, then - current_name can be anything and is interpreted at - lookup time relative to the group which contains the final - component of new_name. For instance, if - current_name is ./foo, - new_name is ./x/y/bar, and a request - is made for ./x/y/bar, then the actual object looked - up is ./x/y/./foo. -

Parameters: -
-
hid_t curr_loc_id -
IN: The file or group identifier for the original object. -
const char * current_name -
IN: Name of the existing object if link is a hard link. - Can be anything for the soft link. -
H5G_link_t link_type -
IN: Link type. - Possible values are H5G_LINK_HARD and - H5G_LINK_SOFT. -
hid_t new_loc_id -
IN: The file or group identifier for the new link. -
const char * new_name -
IN: New name for the object. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): - -
- +
Name: H5Gget_objname_by_idx +
Signature: +
ssize_t H5Gget_objname_by_idx(hid_t loc_id, + hsize_t idx, + char *name, + size_t* size ) +
Purpose: +
Returns a name of an object specified by an index. +
Description: +
H5Gget_objname_by_idx returns a name of the object + specified by the index idx in the group loc_id. +

+ The group is specified by a group identifier loc_id. + If preferred, a file identifier may be passed in loc_id; + that file's root group will be assumed. +

+ idx is the transient index used to iterate through + the objects in the group. + The value of idx is any nonnegative number less than + the total number of objects in the group, which is returned by the + functioin H5Gget_num_objects. + Note that this is a transient index; an object may have a + different index each time a group is opened. +

+ The object name is returned in the user-specified buffer name. +

+ If the size of the provided buffer name is + less or equal the actual object name length, + the object name is truncated to max_size - 1 characters. +

+ Note that if the size of the object's name is unkown, a + preliminary call to H5Gget_objname_by_idx with name + set to NULL will return the length of the object's name. + A second call to H5Gget_objname_by_idx + can then be used to retrieve the actual name. +

Parameters: +
+
hid_t loc_id +
IN: Group or file identifier. +
hsize_t idx +
IN: Transient index identifying object. +
char *name +
IN/OUT: Pointer to user-provided buffer the object name. +
size_t size +
IN: Name length. +
+
Returns: +
Returns the size of the object name if successful, + or 0 if no name is associated with the group identifier. + Otherwise returns a negative value.
- +
-
Name: H5Gunlink -
Signature: -
herr_t H5Gunlink(hid_t loc_id, - const char *name - ) -
Purpose: -
Removes the link to an object from a group. -
Description: -
H5Gunlink removes the object specified by - name from the group graph and decrements the - link count for the object to which name points. - This action eliminates any association between name - and the object to which name pointed. -

- Object headers keep track of how many hard links refer to an object; - when the link count reaches zero, the object can be removed - from the file. Objects which are open are not removed until all - identifiers to the object are closed. -

- If the link count reaches zero, all file space associated with - the object will be released, i.e., identified in memory as freespace. - If the any object identifier is open for the object, the space - will not be released until after the object identifier is closed. -

- Note that space identified as freespace is available for re-use - only as long as the file remains open; once a file has been - closed, the HDF5 library loses track of freespace. See - “Freespace Management” - in the HDF5 User's Guide for further details. -

Warning: -
Exercise care in unlinking groups as it is possible to render data in - a file inaccessible with H5Gunlink. - See The Group Interface - in the HDF5 User's Guide. -
Parameters: -
-
hid_t loc_id -
IN: Identifier of the file or group containing the object. -
const char * name -
IN: Name of the object to unlink. -
-
Returns: -
Returns a non-negative value if successful; - otherwise returns a negative value. -
Non-C API(s): -
- +
Name: H5Gget_objtype_by_idx +
Signature: +
int H5Gget_objtype_by_idx(hid_t loc_id, + hsize_t idx ) +
Purpose: +
Returns the type of an object specified by an index. +
Description: +
H5Gget_objtype_by_idx returns the type of the object + specified by the index idx in the group loc_id. +

+ The group is specified by a group identifier loc_id. + If preferred, a file identifier may be passed in loc_id; + that file's root group will be assumed. +

+ idx is the transient index used to iterate through + the objects in the group. + This parameter is described in more detail in the discussion of + H5Gget_objname_by_idx. +

+ The object type is returned as the function return value: + + + + + +
+      + + H5G_LINK + + + 0 + + Object is a symbolic link. +
  + + + H5G_GROUP + + + 1 + + Object is a group. +
  + + + H5G_DATASET    + + + 2    + + Object is a dataset. +
  + + + H5G_TYPE + + + 3 + + Object is a named datatype. +
+ +

Parameters: +
+
hid_t loc_id +
IN: Group or file identifier. +
hsize_t idx +
IN: Transient index identifying object. +
+
Returns: +
Returns the type of the object if successful. + Otherwise returns a negative value.
@@ -641,6 +785,131 @@ create or access function.
+ +
+
+
Name: H5Glink +
Signature: +
herr_t H5Glink(hid_t loc_id, + H5G_link_t link_type, + const char *current_name, + const char *new_name + ) +
Purpose: +
Creates a link of the specified type from new_name + to current_name. +
Description: +
H5Glink creates a new name for an object that has some current + name, possibly one of many names it currently has. +

+ If link_type is H5G_LINK_HARD, then + current_name must specify the name of an + existing object and both + names are interpreted relative to loc_id, which is + either a file identifier or a group identifier. +

+ If link_type is H5G_LINK_SOFT, then + current_name can be anything and is interpreted at + lookup time relative to the group which contains the final + component of new_name. For instance, if + current_name is ./foo, + new_name is ./x/y/bar, and a request + is made for ./x/y/bar, then the actual object looked + up is ./x/y/./foo. +

Parameters: +
+
hid_t loc_id +
IN: File or group identifier. +
H5G_link_t link_type +
IN: Link type. + Possible values are H5G_LINK_HARD and + H5G_LINK_SOFT. +
const char * current_name +
IN: Name of the existing object if link is a hard link. + Can be anything for the soft link. +
const char * new_name +
IN: New name for the object. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): + +
+ +
+ + + +
+
+
Name: H5Glink2 +
Signature: + +
herr_t H5Glink2( + hid_t curr_loc_id, const char *current_name, + H5G_link_t link_type, + hid_t new_loc_id, const char *new_name ) +
Purpose: +
Creates a link of the specified type from new_name + to current_name. +
Description: + +
H5Glink2 creates a new name for an object that has some current + name, possibly one of many names it currently has. +

+ If link_type is H5G_LINK_HARD, then current_name + must specify the name of an existing object. + In this case, current_name and new_name are interpreted + relative to curr_loc_id and new_loc_id, respectively, + which are either file or group identifiers. +

+ If link_type is H5G_LINK_SOFT, then + current_name can be anything and is interpreted at + lookup time relative to the group which contains the final + component of new_name. For instance, if + current_name is ./foo, + new_name is ./x/y/bar, and a request + is made for ./x/y/bar, then the actual object looked + up is ./x/y/./foo. +

Parameters: +
+
hid_t curr_loc_id +
IN: The file or group identifier for the original object. +
const char * current_name +
IN: Name of the existing object if link is a hard link. + Can be anything for the soft link. +
H5G_link_t link_type +
IN: Link type. + Possible values are H5G_LINK_HARD and + H5G_LINK_SOFT. +
hid_t new_loc_id +
IN: The file or group identifier for the new link. +
const char * new_name +
IN: New name for the object. +
+
Returns: +
Returns a non-negative value if successful; + otherwise returns a negative value. +
Non-C API(s): + +
+ +
+ +
@@ -677,391 +946,96 @@ create or access function.
Returns a non-negative value if successful; otherwise returns a negative value.
Non-C API(s): -
- -
- - - -
-
-
Name: H5Gmove2 -
Signature: -
herr_t H5Gmove2( hid_t src_loc_id, - const char *src_name, hid_t dst_loc_id, - const char *dst_name ) -
Purpose: -
Renames an object within an HDF5 file. -
Description: -
H5Gmove2 renames an object within an HDF5 file. The original - name, src_name, is unlinked from the group graph and the new - name, dst_name, is inserted as an atomic operation. -

-

src_name and dst_name are interpreted relative to - src_name and dst_name, respectively, - which are either file or group identifiers. -
Warning: -
Exercise care in moving groups as it is possible to render data in a file - inaccessible with H5Gmove. See The - Group Interface in the HDF5 User's Guide. -
Parameters: -
-
hid_t src_loc_id -
IN: Original file or group identifier. -
const char *src_name -
IN: Object's original name. -
hid_t dst_loc_id -
IN: Destination file or group identifier. -
const char *dst_name -
IN: Object's new name. -
-
Returns: -
Returns a non-negative value if successful; otherwise returns a negative - value. -
Non-C API(s): -
- -
- - - -
-
-
Name: H5Gget_objinfo -
Signature: -
herr_t H5Gget_objinfo(hid_t loc_id, - const char *name, - hbool_t follow_link, - H5G_stat_t *statbuf - ) -
Purpose: -
Returns information about an object. -
Description: -
H5Gget_objinfo returns information about the - specified object through the statbuf argument. - loc_id (a file or group identifier) and - name together determine the object. - If the object is a symbolic link and follow_link is - zero (0), then the information returned is that for the link itself; - otherwise the link is followed and information is returned about - the object to which the link points. - If follow_link is non-zero but the final symbolic link - is dangling (does not point to anything), then an error is returned. - The statbuf fields are undefined for an error. - The existence of an object can be tested by calling this function - with a null statbuf. -

- H5Gget_objinfo fills in the following data structure: - 

-                  typedef struct H5G_stat_t {
-                      unsigned long fileno[2];
-                      unsigned long objno[2];
-                      unsigned nlink;
-                      int type;
-                      time_t mtime; 
-                      size_t linklen;
-                  } H5G_stat_t
-
- The fileno and objno fields contain - four values which uniquely itentify an object among those - HDF5 files which are open: if all four values are the same - between two objects, then the two objects are the same - (provided both files are still open). -
    -
  • Note that if a file is closed and re-opened, the - value in fileno will change. -
  • If a VFL driver either does not or cannot detect that - two H5Fopen calls referencing the same file - actually open the same file, each will get a different - fileno. -
-

- The nlink field is the number of hard links to - the object or zero when information is being returned about a - symbolic link (symbolic links do not have hard links but - all other objects always have at least one). - The type field contains the type of the object, - one of - H5G_GROUP, - H5G_DATASET, - H5G_LINK, or - H5G_TYPE. - The mtime field contains the modification time. - If information is being returned about a symbolic link then - linklen will be the length of the link value - (the name of the pointed-to object with the null terminator); - otherwise linklen will be zero. - Other fields may be added to this structure in the future. -

Note: -
Some systems will be able to record the time accurately but - unable to retrieve the correct time; such systems (e.g., Irix64) - will report an mtime value of 0 (zero). -
Parameters: -
-
hid_t loc_id -
IN: File or group identifier. -
const char *name -
IN: Name of the object for which status is being sought. -
hbool_t follow_link -
IN: Link flag. -
H5G_stat_t *statbuf -
OUT: Buffer in which to return information about the object. -
-
Returns: -
Returns a non-negative value if successful, with the fields of - statbuf (if non-null) initialized. - Otherwise returns a negative value. - - -
- - - - - - - - - - - -
-
-
Name: H5Gget_num_objs -
Signature: -
herr_t H5Gget_num_objs(hid_t loc_id, - hsize_t* num_obj) -
Purpose: -
Returns number of objects in the group specified by its identifier -
Description: -
H5Gget_num_objs returns number of objects in a group. - Group is specified by its identifier loc_id. - If file identifier is passed in, then number of objects in the - root group is returned. -
Parameters: -
-
hid_t loc_id -
IN: Identifier of the group or the file -
hsize_t* num_obj -
OUT: Number of objects in the group. -
-
Returns: -
Returns positive value if successful; - otherwise returns a negative value. -
- - - - - -
-
-
Name: H5Gget_objname_by_idx -
Signature: -
ssize_t H5Gget_objname_by_idx(hid_t loc_id, - hsize_t idx, - char *name, - size_t* size ) -
Purpose: -
Returns a name of an object specified by an index. -
Description: -
H5Gget_objname_by_idx returns a name of the object - specified by the index idx in the group loc_id. -

- The group is specified by a group identifier loc_id. - If preferred, a file identifier may be passed in loc_id; - that file's root group will be assumed. -

- idx is the transient index used to iterate through - the objects in the group. - The value of idx is any nonnegative number less than - the total number of objects in the group, which is returned by the - functioin H5Gget_num_objects. - Note that this is a transient index; an object may have a - different index each time a group is opened. -

- The object name is returned in the user-specified buffer name. -

- If the size of the provided buffer name is - less or equal the actual object name length, - the object name is truncated to max_size - 1 characters. -

- Note that if the size of the object's name is unkown, a - preliminary call to H5Gget_objname_by_idx with name - set to NULL will return the length of the object's name. - A second call to H5Gget_objname_by_idx - can then be used to retrieve the actual name. -

Parameters: -
-
hid_t loc_id -
IN: Group or file identifier. -
hsize_t idx -
IN: Transient index identifying object. -
char *name -
IN/OUT: Pointer to user-provided buffer the object name. -
size_t size -
IN: Name length. -
-
Returns: -
Returns the size of the object name if successful, - or 0 if no name is associated with the group identifier. - Otherwise returns a negative value. +
+
- +
-
Name: H5Gget_objtype_by_idx -
Signature: -
int H5Gget_objtype_by_idx(hid_t loc_id, - hsize_t idx ) -
Purpose: -
Returns the type of an object specified by an index. -
Description: -
H5Gget_objtype_by_idx returns the type of the object - specified by the index idx in the group loc_id. -

- The group is specified by a group identifier loc_id. - If preferred, a file identifier may be passed in loc_id; - that file's root group will be assumed. -

- idx is the transient index used to iterate through - the objects in the group. - This parameter is described in more detail in the discussion of - H5Gget_objname_by_idx. -

- The object type is returned as the function return value: - - - - - -
-      - - H5G_LINK - - - 0 - - Object is a symbolic link. -
  - - - H5G_GROUP - - - 1 - - Object is a group. -
  - - - H5G_DATASET    - - - 2    - - Object is a dataset. -
  - - - H5G_TYPE - - - 3 - - Object is a named datatype. -
- -

Parameters: -
-
hid_t loc_id -
IN: Group or file identifier. -
hsize_t idx -
IN: Transient index identifying object. -
-
Returns: -
Returns the type of the object if successful. - Otherwise returns a negative value. +
Name: H5Gmove2 +
Signature: +
herr_t H5Gmove2( hid_t src_loc_id, + const char *src_name, hid_t dst_loc_id, + const char *dst_name ) +
Purpose: +
Renames an object within an HDF5 file. +
Description: +
H5Gmove2 renames an object within an HDF5 file. The original + name, src_name, is unlinked from the group graph and the new + name, dst_name, is inserted as an atomic operation. +

+

src_name and dst_name are interpreted relative to + src_name and dst_name, respectively, + which are either file or group identifiers. +
Warning: +
Exercise care in moving groups as it is possible to render data in a file + inaccessible with H5Gmove. See The + Group Interface in the HDF5 User's Guide. +
Parameters: +
+
hid_t src_loc_id +
IN: Original file or group identifier. +
const char *src_name +
IN: Object's original name. +
hid_t dst_loc_id +
IN: Destination file or group identifier. +
const char *dst_name +
IN: Object's new name. +
+
Returns: +
Returns a non-negative value if successful; otherwise returns a negative + value. +
Non-C API(s): +
+
- - - - - - - - +
-
Name: H5Gget_linkval +
Name: H5Gopen
Signature: -
herr_t H5Gget_linkval(hid_t loc_id, - const char *name, - size_t size, - char *value +
hid_t H5Gopen(hid_t loc_id, + const char *name )
Purpose: -
Returns the name of the object that the symbolic link points to. +
Opens an existing group for modification and returns a group + identifier for that group.
Description: -
H5Gget_linkval returns size - characters of the name of the object that the symbolic link name points to. -

- The parameter loc_id is a file or group identifier. -

- The parameter name must be a symbolic link pointing to - the desired object and must be defined relative to loc_id. +

H5Gopen opens an existing group with the specified + name at the specified location, loc_id.

- If size is smaller than the size of the returned object name, then - the name stored in the buffer value will not be null terminated. -

- This function fails if name is not a symbolic link. - The presence of a symbolic link can be tested by passing zero for - size and NULL for value. + The location is identified by a file or group identifier

- This function should be used only after H5Gget_objinfo has been called - to verify that name is a symbolic link. + H5Gopen returns a group identifier for the group + that was opened. This group identifier should be released by + calling H5Gclose when it is no longer needed.

Parameters:
hid_t loc_id -
IN: Identifier of the file or group. -
const char *name -
IN: Symbolic link to the object whose name is to be returned. -
size_t size -
IN: Maximum number of characters of value - to be returned. -
char *value -
OUT: A buffer to hold the name of the object being sought. +
IN: File or group identifier within which group is to be open. +
const char * name +
IN: Name of group to open.
Returns: -
Returns a non-negative value, with the link value in value, - if successful. - Otherwise returns a negative value. +
Returns a valid group identifier if successful; + otherwise returns a negative value.
Non-C API(s): -
+--> +
- - - -
@@ -1121,48 +1091,55 @@ create or access function.
- +
-
Name: H5Gget_comment +
Name: H5Gunlink
Signature: -
herr_t H5Gget_comment(hid_t loc_id, - const char *name, - size_t bufsize, - char *comment +
herr_t H5Gunlink(hid_t loc_id, + const char *name )
Purpose: -
Retrieves comment for specified object. +
Removes the link to an object from a group.
Description: -
H5Gget_comment retrieves the comment for the the - object name. The comment is returned in the buffer - comment. +
H5Gunlink removes the object specified by + name from the group graph and decrements the + link count for the object to which name points. + This action eliminates any association between name + and the object to which name pointed.

- At most bufsize characters, including a null - terminator, are copied. The result is not null terminated - if the comment is longer than the supplied buffer. + Object headers keep track of how many hard links refer to an object; + when the link count reaches zero, the object can be removed + from the file. Objects which are open are not removed until all + identifiers to the object are closed.

- If an object does not have a comment, the empty string - is returned. + If the link count reaches zero, all file space associated with + the object will be released, i.e., identified in memory as freespace. + If the any object identifier is open for the object, the space + will not be released until after the object identifier is closed. +

+ Note that space identified as freespace is available for re-use + only as long as the file remains open; once a file has been + closed, the HDF5 library loses track of freespace. See + “Freespace Management” + in the HDF5 User's Guide for further details. +

Warning: +
Exercise care in unlinking groups as it is possible to render data in + a file inaccessible with H5Gunlink. + See The Group Interface + in the HDF5 User's Guide.
Parameters:
hid_t loc_id -
IN: Identifier of the file or group. -
const char *name -
IN: Name of the object whose comment is to be set or reset. -
size_t bufsize -
IN: Anticipated size of the buffer required to hold - comment. -
char *comment -
OUT: The comment. +
IN: Identifier of the file or group containing the object. +
const char * name +
IN: Name of the object to unlink.
Returns: -
Returns the number of characters in the comment, - counting the null terminator, if successful; the value - returned may be larger than bufsize. - Otherwise returns a negative value. +
Returns a non-negative value if successful; + otherwise returns a negative value.
Non-C API(s): -
-
@@ -1204,14 +1180,13 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003
diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html index 8f3dede..409de63 100644 --- a/doc/html/RM_H5I.html +++ b/doc/html/RM_H5I.html @@ -61,8 +61,7 @@ And in this document, the
-
-
+

H5I: Identifier Interface

@@ -125,62 +124,6 @@ facilitate moving easily between them. - -
-
-
Name: H5Iget_type -
Signature: -
H5I_type_t H5Iget_type(hid_t obj_id) -
Purpose: -
Retrieves the type of an object. -
Description: -
H5Iget_type retrieves the type of the object - identified by obj_id. -

- Valid types returned by the function are - - - - - - - -
    H5I_FILE - File
    H5I_GROUP - Group
    H5I_DATATYPE - Datatype
    H5I_DATASPACE - Dataspace
    H5I_DATASET - Dataset
    H5I_ATTR - Attribute
- If no valid type can be determined or the identifier - submitted is invalid, the function returns - - -
    H5I_BADID - Invalid identifier
-

- This function is of particular value in determining the - type of object closing function (H5Dclose, - H5Gclose, etc.) to call after a call to - H5Rdereference. -

Parameters: -
-
hid_t obj_id -
IN: Object identifier whose type is to be determined. -
-
Returns: -
Returns the object type if successful; - otherwise H5I_BADID. -
Non-C API(s): -
- -
- -
@@ -240,6 +183,61 @@ facilitate moving easily between them. -->
+ + +
+
+
Name: H5Iget_type +
Signature: +
H5I_type_t H5Iget_type(hid_t obj_id) +
Purpose: +
Retrieves the type of an object. +
Description: +
H5Iget_type retrieves the type of the object + identified by obj_id. +

+ Valid types returned by the function are + + + + + + + +
    H5I_FILE + File
    H5I_GROUP + Group
    H5I_DATATYPE + Datatype
    H5I_DATASPACE + Dataspace
    H5I_DATASET + Dataset
    H5I_ATTR + Attribute
+ If no valid type can be determined or the identifier + submitted is invalid, the function returns + + +
    H5I_BADID + Invalid identifier
+

+ This function is of particular value in determining the + type of object closing function (H5Dclose, + H5Gclose, etc.) to call after a call to + H5Rdereference. +

Parameters: +
+
hid_t obj_id +
IN: Object identifier whose type is to be determined. +
+
Returns: +
Returns the object type if successful; + otherwise H5I_BADID. +
Non-C API(s): +
+ +
@@ -274,14 +272,13 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003
diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index fb20a2b..fa725d5 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -61,8 +61,7 @@ And in this document, the
-
-
+

H5P: Property List Interface

Property List API Functions

@@ -155,7 +154,7 @@ which require many different parameters to be easily manipulated.
  • H5Pget_fapl_stream
  • H5Pget_driver -
  • H5Pget_driver_info +
  • H5Pset_meta_block_size
  • H5Pget_meta_block_size
  • H5Pset_sieve_buf_size @@ -298,7 +297,7 @@ See further notes in the description of each function.
  • H5Pget_class_name
  • H5Pget_class_parent
  • H5Pget_driver -
  • H5Pget_driver_info +
  • H5Pget_dxpl_mpio   ||
  • H5Pget_dxpl_multi
  • H5Pget_edc_check @@ -603,62 +602,31 @@ facilitate moving easily between them. - +
    -
    Name: H5Pcreate +
    Name: H5Pall_filters_avail
    Signature: -
    hid_t H5Pcreate(H5P_class_t type - ) +
    htri_t H5Pall_filters_avail(hid_t dcpl_id)
    Purpose: -
    Creates a new property as an instance of a property list class. +
    Verifies that all required filters are available.
    Description: -
    H5Pcreate creates a new property as an instance of some - property list class. The new property list is initialized - with default values for the specified class. The classes are: -
    -
    H5P_FILE_CREATE -
    Properties for file creation. - See Files - in the HDF User's Guide - for details about the file creation properties. -
    H5P_FILE_ACCESS -
    Properties for file access. - See Files - in the HDF User's Guide - for details about the file creation properties. -
    H5P_DATASET_CREATE -
    Properties for dataset creation. - See Datasets - in the HDF User's Guide - for details about dataset creation properties. -
    H5P_DATASET_XFER -
    Properties for raw data transfer. - See Datasets - in the HDF User's Guide - for details about raw data transfer properties. -
    H5P_MOUNT -
    Properties for file mounting. - With this parameter, H5Pcreate - creates and returns a new mount property list - initialized with default values. -
    -

    - This property list must eventually be closed with - H5Pclose; - otherwise, errors are likely to occur. +

    H5Pall_filters_avail verifies that all of the filters + set in the dataset creation property list dcpl_id are + currently available.
    Parameters:
    -
    H5P_class_t type -
    IN: The type of property list to create. +
    hid_t dcpl_id +
    IN: Dataset creation property list identifier.
    Returns: -
    Returns a property list identifier (plist) if successful; - otherwise Fail (-1). -
    Non-C API(s): -
    Returns TRUE if all filters are available + and FALSE if one or more is not currently available.
    + Returns FAIL, a negative value, on error. + @@ -697,35 +665,88 @@ facilitate moving easily between them.
    - +
    -
    Name: H5Pget_class +
    Name: H5Pclose_class +
    Signature: -
    H5P_class_t H5Pget_class(hid_t plist - ) +
    herr_t H5Pclose_class( + hid_t class + ) +
    Purpose: -
    Returns the property list class for a property list. +
    Closes an existing property list class. +
    Description: -
    H5Pget_class returns the property list class for the - property list identified by the plist parameter. - Valid property list classes are defined in the description of - H5Pcreate. +
    Removes a property list class from the library. + +

    + Existing property lists of this class will continue to exist, + but new ones are not able to be created. +

    Parameters: -
    -
    hid_t plist -
    IN: Identifier of property list to query. -
    +
      + + + +
      hid_t classIN: Property list class to close
    +
    Returns: -
    Returns a property list class if successful. - Otherwise returns H5P_NO_CLASS (-1). -
    Non-C API(s): -
    - +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    + +
    + + + +
    +
    +
    Name: H5Pclose_list + +
    Signature: +
    herr_t H5Pclose_list( + hid_t plist + ) + +
    Purpose: +
    Closes a property list. + +
    Description: +
    H5Pclose_list closes a property list. + +

    + If a close callback exists for the property list class, + it is called before the property list is destroyed. + If close callbacks exist for any individual properties + in the property list, they are called after the class + close callback. + +

    Parameters: +
      + + +
      hid_t plist + IN: Property list to close
    + +
    Returns: +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    +
    @@ -761,85 +782,215 @@ facilitate moving easily between them. - +
    -
    Name: H5Pcreate_class +
    Name: H5Pcopy_prop
    Signature: -
    hid_t H5Pcreate_class( - hid_t class, - const char *name, - H5P_cls_create_func_t create, - H5P_cls_copy_func_t copy, - H5P_cls_close_func_t close - ) +
    herr_t H5Pcopy_prop( + hid_t dst_id, + hid_t src_id, + const char *name + )
    Purpose: -
    Creates a new property list class. +
    Copies a property from one list or class to another.
    Description: -
    H5Pcreate_class registers a new property list class - with the library. - The new property list class can inherit from an existing property - list class or may be derived from the default "empty" class. - New classes with inherited properties from existing classes - may not remove those existing properties, only add or remove - their own class properties. -

    +
    H5Pcopy_prop copies a property from one property + list or class to another. + +

    + If a property is copied from one class to another, all the property + information will be first deleted from the destination class and + then the property information will be copied from the source class + into the destination class. - The create routine is called when a new property list - of this class is being created. - The H5P_cls_create_func_t callback function is defined - as follows: -

      typedef herr_t (*H5P_cls_create_func_t)( - hid_t prop_id, - void * create_data - ); -
    - The parameters to this callback function are defined as follows: -
      - - - - - - -
      hid_t prop_idIN: The identifier of the property list being created
      void * create_dataIN/OUT: User pointer to any class creation information needed
    - The create routine is called after any registered - create function is called for each property value. - If the create routine returns a negative value, - the new list is not returned to the user and the - property list creation routine returns an error value. -

    +

    + If a property is copied from one list to another, the property + will be first deleted from the destination list (generating a call + to the close callback for the property, if one exists) + and then the property is copied from the source list to the + destination list (generating a call to the copy + callback for the property, if one exists). - The copy routine is called when an existing property list - of this class is copied. - The H5P_cls_copy_func_t callback function - is defined as follows: -

      typedef herr_t (*H5P_cls_copy_func_t)( - hid_t prop_id, - void * copy_data - ); -
    - The parameters to this callback function are defined as follows: -
      - - - - - - -
      hid_t prop_idIN: The identifier of the property list created by copying
      void * copy_dataIN/OUT: User pointer to any class copy information needed
    - The copy routine is called after any registered - copy function is called for each property value. - If the copy routine returns a negative value, the new list - is not returned to the user and thenproperty list copy routine returns - an error value. -

    +

    + If the property does not exist in the class or list, this call is + equivalent to calling H5Pregister or H5Pinsert + (for a class or list, as appropriate) and the create + callback will be called in the case of the property being + copied into a list (if such a callback exists for the property). - The close routine is called when a property list of this - class +

    Parameters: +
      + + + + + + + + + +
      hid_t dst_idIN: Identifier of the destination property list or + class
      hid_t src_idIN: Identifier of the source property list or class
      const char *nameIN: Name of the property to copy
    + +
    Returns: +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    + +
    + + + +
    +
    +
    Name: H5Pcreate +
    Signature: +
    hid_t H5Pcreate(H5P_class_t type + ) +
    Purpose: +
    Creates a new property as an instance of a property list class. +
    Description: +
    H5Pcreate creates a new property as an instance of some + property list class. The new property list is initialized + with default values for the specified class. The classes are: +
    +
    H5P_FILE_CREATE +
    Properties for file creation. + See Files + in the HDF User's Guide + for details about the file creation properties. +
    H5P_FILE_ACCESS +
    Properties for file access. + See Files + in the HDF User's Guide + for details about the file creation properties. +
    H5P_DATASET_CREATE +
    Properties for dataset creation. + See Datasets + in the HDF User's Guide + for details about dataset creation properties. +
    H5P_DATASET_XFER +
    Properties for raw data transfer. + See Datasets + in the HDF User's Guide + for details about raw data transfer properties. +
    H5P_MOUNT +
    Properties for file mounting. + With this parameter, H5Pcreate + creates and returns a new mount property list + initialized with default values. +
    +

    + This property list must eventually be closed with + H5Pclose; + otherwise, errors are likely to occur. +

    Parameters: +
    +
    H5P_class_t type +
    IN: The type of property list to create. +
    +
    Returns: +
    Returns a property list identifier (plist) if successful; + otherwise Fail (-1). +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Pcreate_class + +
    Signature: +
    hid_t H5Pcreate_class( + hid_t class, + const char *name, + H5P_cls_create_func_t create, + H5P_cls_copy_func_t copy, + H5P_cls_close_func_t close + ) + +
    Purpose: +
    Creates a new property list class. + +
    Description: +
    H5Pcreate_class registers a new property list class + with the library. + The new property list class can inherit from an existing property + list class or may be derived from the default "empty" class. + New classes with inherited properties from existing classes + may not remove those existing properties, only add or remove + their own class properties. +

    + + The create routine is called when a new property list + of this class is being created. + The H5P_cls_create_func_t callback function is defined + as follows: +
      typedef herr_t (*H5P_cls_create_func_t)( + hid_t prop_id, + void * create_data + ); +
    + The parameters to this callback function are defined as follows: +
      + + + + + + +
      hid_t prop_idIN: The identifier of the property list being created
      void * create_dataIN/OUT: User pointer to any class creation information needed
    + The create routine is called after any registered + create function is called for each property value. + If the create routine returns a negative value, + the new list is not returned to the user and the + property list creation routine returns an error value. +

    + + The copy routine is called when an existing property list + of this class is copied. + The H5P_cls_copy_func_t callback function + is defined as follows: +
      typedef herr_t (*H5P_cls_copy_func_t)( + hid_t prop_id, + void * copy_data + ); +
    + The parameters to this callback function are defined as follows: +
      + + + + + + +
      hid_t prop_idIN: The identifier of the property list created by copying
      void * copy_dataIN/OUT: User pointer to any class copy information needed
    + The copy routine is called after any registered + copy function is called for each property value. + If the copy routine returns a negative value, the new list + is not returned to the user and thenproperty list copy routine returns + an error value. +

    + + The close routine is called when a property list of this + class is being closed. The H5P_cls_close_func_t callback function is defined as follows: @@ -941,287 +1092,89 @@ facilitate moving easily between them.
    - +
    -
    Name: H5Pregister +
    Name: H5Pequal
    Signature: -
    herr_t H5Pregister( - hid_t class, - const char * name, - size_t size, - void * default, - H5P_prp_create_func_t create, - H5P_prp_set_func_t set, - H5P_prp_get_func_t get, - H5P_prp_delete_func_t delete, - H5P_prp_copy_func_t copy, - H5P_prp_close_func_t close - ) - +
    htri_t H5Pequal( + hid_t id1, + hid_t id2 + ) +
    Purpose: -
    Registers a permanent property with a property list class. - -
    Description: -
    H5Pregister registers a new property with a - property list class. - The property will exist in all property list objects of - class created after this routine finishes. The name - of the property must not already exist, or this routine will fail. - The default property value must be provided and all new property - lists created with this property will have the property value set - to the default value. Any of the callback routines may be set to - NULL if they are not needed. +
    Compares two property lists or classes for equality. -

    - Zero-sized properties are allowed and do not store any data in the - property list. These may be used as flags to indicate the presence - or absence of a particular piece of information. The default pointer - for a zero-sized property may be set to NULL. - The property create and close callbacks - are called for zero-sized properties, but the set and - get callbacks are never called. -

    +
    Description: +
    H5Pequal compares two property lists or classes + to determine whether they are equal to one another. - The create routine is called when a new property list - with this property is being created. - The H5P_prp_create_func_t callback function is defined - as follows: -
      typedef herr_t (*H5P_prp_create_func_t)( - const char *name, - size_t size, - void *initial_value); -
    - The parameters to this callback function are defined as follows: +

    + Either both id1 and id2 must be + property lists or both must be classes; comparing a list to a + class is an error. + +

    Parameters:
      - - - - - + + - - + +
      const char *nameIN: The name of the property being modified
      size_t sizeIN: The size of the property in bytes
      hid_t id1IN: First property object to be compared
      void *initial_valueIN/OUT: The default value for the property being created, - which will be passed to H5Pregister
      hid_t id2IN: Second property object to be compared
    - The create routine may modify the value to be set and - those changes will be stored as the initial value of the property. - If the create routine returns a negative value, - the new property value is not copied into the property and the - create routine returns an error value. -

    - - The set routine is called before a new value is copied - into the property. - The H5P_prp_set_func_t callback function is defined - as follows: -
      typedef herr_t (*H5P_prp_set_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *new_value); -
    - The parameters to this callback function are defined as follows: -
      - - - - - - - - - - - - -
      hid_t prop_idIN: The identifier of the property list being modified
      const char *nameIN: The name of the property being modified
      size_t sizeIN: The size of the property in bytes
      void **new_valueIN/OUT: Pointer to new value pointer for the property being - modified
    - The set routine may modify the value pointer to be set - and those changes will be used when setting the property's value. - If the set routine returns a negative value, the new - property value is not copied into the property and the - set routine returns an error value. - The set routine will not be called for the initial - value, only the create routine will be called. -

    - Note: - The set callback function may be useful - to range check the value being set for the property - or may perform some tranformation or translation of the - value set. The get callback would then - reverse the transformation or translation. - A single get or set callback - could handle multiple properties by - performing different actions based on the - property name or other properties in the property list. -

    - The get routine is called when a value is retrieved - from a property value. - The H5P_prp_get_func_t callback function is defined - as follows: -

      typedef herr_t (*H5P_prp_get_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *value); -
    - The parameters to the callback function are defined as follows: -
      - - - - - - - - - - - - -
      hid_t prop_idIN: The identifier of the property list being queried
      const char * nameIN: The name of the property being queried
      size_t sizeIN: The size of the property in bytes
      void * valueIN/OUT: The value of the property being returned
    - The get routine may modify the value to be returned from - the query and those changes will be returned to the calling routine. - If the set routine returns a negative value, the query - routine returns an error value. -

    +
    Returns: +
    Success: TRUE (positive) if equal; FALSE (zero) if unequal +
    Failure: a negative value - The delete routine is called when a property is being - deleted from a property list. - The H5P_prp_delete_func_t callback function is defined - as follows: -
      typedef herr_t (*H5P_prp_delete_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *value); -
    - The parameters to the callback function are defined as follows: -
      - - - - - - - - - - - - -
      hid_t prop_idIN: The identifier of the property list the property is being - deleted from
      const char * nameIN: The name of the property in the list
      size_t sizeIN: The size of the property in bytes
      void * valueIN: The value for the property being deleted
    - The delete routine may modify the value passed in, - but the value is not used by the library when the delete - routine returns. If the delete routine returns - a negative value, the property list delete routine returns - an error value but the property is still deleted. -

    +
    Non-C APIs: +
    + +
    - The copy routine is called when a new property list with - this property is being created through a copy operation. - The H5P_prp_copy_func_t callback function is defined - as follows: -
      typedef herr_t (*H5P_prp_copy_func_t)( - const char *name, - size_t size, - void *value); -
    - The parameters to the callback function are defined as follows: -
      - - - - - - - - - -
      const char *nameIN: The name of the property being copied
      size_t sizeIN: The size of the property in bytes
      void *valueIN/OUT: The value for the property being copied
    - The copy routine may modify the value to be set and - those changes will be stored as the new value of the property. - If the copy routine returns a negative value, - the new property value is not copied into the property and - the copy routine returns an error value. -

    + + +
    +
    +
    Name: H5Pexist - The close routine is called when a property list with - this property is being closed. - The H5P_prp_close_func_t callback function is defined - as follows: -
      typedef herr_t (*H5P_prp_close_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *value); -
    - The parameters to the callback function are defined as follows: +
    Signature: +
    htri_t H5Pexist( + hid_t id; + const char *name + ) + +
    Purpose: +
    Queries whether a property name exists in a property list + or class. + +
    Description: +
    H5Pexist determines whether a property exists + within a property list or class. + +
    Parameters:
      - - + + - - - - - - - +
      hid_t prop_idIN: The identifier of the property list being - closed
      hid_t idIN: Identifier for the property to query
      const char *nameIN: The name of the property in the list
      size_t sizeIN: The size of the property in bytes
      void *valueIN: The value for the property being closed
      IN: Name of property to check for
    - The close routine may modify the value passed in, - but the value is not used by the library when the - close routine returns. - If the close routine returns a negative value, - the property list close routine returns an error value but - the property list is still closed. - -
    Parameters: -
      -
      hid_t class -
      IN: Property list class to register permanent property - within -
      const char * name -
      IN: Name of property to register -
      size_t size -
      IN: Size of property in bytes -
      void * default -
      IN: Default value for property in newly created property - lists -
      H5P_prp_create_func_t create -
      IN: Callback routine called when a property list is being - created and the property value will be initialized -
      H5P_prp_set_func_t set -
      IN: Callback routine called before a new value is copied - into the property's value -
      H5P_prp_get_func_t get -
      IN: Callback routine called when a property value is - retrieved from the property -
      H5P_prp_delete_func_t delete -
      IN: Callback routine called when a property is deleted from - a property list -
      H5P_prp_copy_func_t copy -
      IN: Callback routine called when a property is copied from - a property list -
      H5P_prp_close_func_t close -
      IN: Callback routine called when a property list is being - closed and the property value will be disposed of -
    -
    Returns: -
    Success: a non-negative value +
    Returns: +
    Success: a positive value if the property exists in the + property object; zero if the property does not exist
    Failure: a negative value
    Non-C APIs: -
    - +
    -
    Name: H5Pinsert - +
    Name: H5Pfill_value_defined
    Signature: -
    herr_t H5Pinsert( - hid_t plid, - const char *name, - size_t size, - void *value, - H5P_prp_set_func_t set, - H5P_prp_get_func_t get, - H5P_prp_delete_func_t delete, - H5P_prp_copy_func_t copy, - H5P_prp_close_func_t close - ) - +
    herr_t H5Pfill_value_defined(hid_t plist_id, + H5D_fill_value_t *status + )
    Purpose: -
    Registers a temporary property with a property list. - +
    Determines whether fill value is defined.
    Description: -
    H5Pinsert create a new property in a property list. - The property will exist only in this property list and copies made - from it. - -

    - The initial property value must be provided in - value and the property value will be set accordingly. - -

    - The name of the property must not already exist in this list, - or this routine will fail. - -

    - The set and get callback routines may - be set to NULL if they are not needed. +

    H5Pfill_value_defined determines whether a fill value + is defined in the dataset creation property list plist_id. +

    + Valid values returnrd in status are as follows: + +
         + H5D_FILL_VALUE_UNDEFINED + + Fill value is undefined. +
    + H5D_FILL_VALUE_DEFAULT + + Fill value is the library default. +
    + H5D_FILL_VALUE_USER_DEFINED   + + Fill value is defined by the application. +
    +

    Note: +
    H5Pfill_value_defined is designed for use in + concert with the dataset fill value properties functions + H5Pget_fill_value and H5Pget_fill_time. +

    + See H5Dcreate for + further cross-references. +

    Parameters: +
    +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    H5D_fill_value_t *status +
    OUT: Status of fill value in property list. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    -

    - Zero-sized properties are allowed and do not store any data in the - property list. The default value of a zero-size property may be set - to NULL. They may be used to indicate the presence or absence of a - particular piece of information. -

    + + +
    +
    +
    Name: H5Pget - The set routine is called before a new value is copied - into the property. - The H5P_prp_set_func_t calback function is defined - as follows: -
      typedef herr_t (*H5P_prp_set_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *new_value); -
    - The parameters to the callback function are defined as follows: -
      - - - - - - - - - - - - -
      hid_t prop_idIN: The identifier of the property list being modified
      const char *nameIN: The name of the property being modified
      size_t sizeIN: The size of the property in bytes
      void **new_valueIN: Pointer to new value pointer for the property being - modified
    - The set routine may modify the value pointer to be set - and those changes will be used when setting the property's value. - If the set routine returns a negative value, the new - property value is not copied into the property and the set routine - returns an error value. - The set routine will be called for the initial value. -

    - Note: - The set callback function may be useful - to range check the value being set for the property - or may perform some tranformation or translation of the - value set. The get callback would then - reverse the transformation or translation. - A single get or set callback - could handle multiple properties by - performing different actions based on the - property name or other properties in the property list. +

    Signature: +
    herr_t H5Pget( + hid_t plid, + const char *name, + void *value + ) + +
    Purpose: +
    Queries the value of a property. +
    Description: +
    H5Pget retrieves a copy of the value for a property + in a property list. If there is a get callback routine + registered for this property, the copy of the value of the property + will first be passed to that routine and any changes to the copy of + the value will be used when returning the property value from this + routine. +

    - The get routine is called when a value is retrieved - from a property value. - The H5P_prp_get_func_t callback functioin is defined - as follows: -

      typedef herr_t (*H5P_prp_get_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *value); -
    - where the parameters to the callback function are: + This routine may be called for zero-sized properties with the + value set to NULL. The get routine + will be called with a NULL value if the callback exists. + +

    + The property name must exist or this routine will fail. + +

    + If the get callback routine returns an error, + value will not be modified. + +

    Parameters:
      - - + + - - - - + - +
      hid_t prop_idIN: The identifier of the property list being queried
      hid_t plidIN: Identifier of the property list to query
      const char *nameIN: The name of the property being queried
      size_t sizeIN: The size of the property in bytes
      IN: Name of property to query
      void *valueIN: The value of the property being returned
      OUT: Pointer to a location to which to copy the value of + of the property
    - The get routine may modify the value to be returned from - the query and those changes will be preserved. - If the get routine returns a negative value, the query - routine returns an error value. -

    - The delete routine is called when a property is being - deleted from a property list. - The H5P_prp_delete_func_t callback function is defined - as follows: -
      typedef herr_t (*H5P_prp_delete_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *value); -
    - where the parameters to the callback function are: -
      - - - - - - - - - - - - -
      hid_t prop_idIN: The identifier of the property list the property is - being deleted from
      const char * nameIN: The name of the property in the list
      size_t sizeIN: The size of the property in bytes
      void * valueIN: The value for the property being deleted
    - The delete routine may modify the value passed in, - but the value is not used by the library when the delete - routine returns. If the delete routine returns a - negative value, the property list delete routine returns an - error value but the property is still deleted. -

    - - The copy routine is called when a new property list - with this property is being created through a copy operation. - The H5P_prp_copy_func_t collback function is defined - as follows: -
      typedef herr_t (*H5P_prp_copy_func_t)( - const char *name, - size_t size, - void *value); -
    - where the parameters to the callback function are: -
      - - - - - - - - - -
      const char *nameIN: The name of the property being copied
      size_t sizeIN: The size of the property in bytes
      void * valueIN/OUT: The value for the property being copied
    - The copy routine may modify the value to be set and - those changes will be stored as the new value of the property. - If the copy routine returns a negative value, the - new property value is not copied into the property and the - copy routine returns an error value. - -

    The close routine is called when a property list - with this property is being closed. - The H5P_prp_close_func_t callback function is defined - as follows: -

      typedef herr_t (*H5P_prp_close_func_t)( - hid_t prop_id, - const char *name, - size_t size, - void *value); -
    - The parameters to the callback function are defined as follows: -
      - - - - - - - - - - - - -
      hid_t prop_idIN: The ID of the property list being closed
      const char *nameIN: The name of the property in the list
      size_t sizeIN: The size of the property in bytes
      void *valueIN: The value for the property being closed
    - The close routine may modify the value passed in, the value - is not used by the library when the close routine returns. - If the close routine returns a negative value, the - property list close routine returns an error value but the property list - is still closed. - -

    - Note: - There is no create callback routine for temporary property - list objects; the initial value is assumed to have any necessary setup - already performed on it. - -

    Parameters: -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      hid_t plidIN: Property list identifier to create temporary property - within
      const char *nameIN: Name of property to create
      size_t sizeIN: Size of property in bytes
      void *valueIN: Initial value for the property
      H5P_prp_set_func_t setIN: Callback routine called before a new value is copied into - the property's value
      H5P_prp_get_func_t getIN: Callback routine called when a property value is retrieved - from the property
      H5P_prp_delete_func_t deleteIN: Callback routine called when a property is deleted from - a property list
      H5P_prp_copy_func_t copyIN: Callback routine called when a property is copied from - an existing property list
      H5P_prp_close_func_t closeIN: Callback routine called when a property list is being closed - and the property value will be disposed of
    - -
    Returns: -
    Success: a non-negative value -
    Failure: a negative value +
    Returns: +
    Success: a non-negative value +
    Failure: a negative value
    Non-C APIs: -
    - +
    -
    Name: H5Pset - +
    Name: H5Pget_alignment
    Signature: -
    herr_t H5Pset( - hid_t plid, - const char *name, - void *value) - ) - +
    herr_t H5Pget_alignment(hid_t plist, + hsize_t *threshold, + hsize_t *alignment + )
    Purpose: -
    Sets a property list value. - +
    Retrieves the current settings for alignment properties from a + file access property list.
    Description: -
    H5Pset sets a new value for a property in a - property list. If there is a set callback - routine registered for this property, the value will be - passed to that routine and any changes to the value - will be used when setting the property value. - The information pointed to by the value pointer - (possibly modified by the set callback) is copied into - the property list value and may be changed by the application making - the H5Pset call without affecting the property value. - -

    - The property name must exist or this routine will fail. - -

    - If the set callback routine returns an error, the - property value will not be modified. - -

    - This routine may not be called for zero-sized properties - and will return an error in that case. - +

    H5Pget_alignment retrieves the current settings for + alignment properties from a file access property list. + The threshold and/or alignment pointers + may be null pointers (NULL).
    Parameters: -
      - - - - - - -
      hid_t plid; - IN: Property list identifier to modify
      const char *name; - IN: Name of property to modify
      void *value; - IN: Pointer to value to set the property to
    - -
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    +
    hid_t plist +
    IN: Identifier of a file access property list. +
    hsize_t *threshold +
    OUT: Pointer to location of return threshold value. +
    hsize_t *alignment +
    OUT: Pointer to location of return alignment value. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Pexist - +
    Name: H5Pget_alloc_time
    Signature: -
    htri_t H5Pexist( - hid_t id; - const char *name - ) - +
    herr_t H5Pget_alloc_time(hid_t plist_id, + H5D_alloc_time_t *alloc_time + )
    Purpose: -
    Queries whether a property name exists in a property list - or class. - +
    Retrieves the timing for storage space allocation.
    Description: -
    H5Pexist determines whether a property exists - within a property list or class. - +
    H5Pget_alloc_time retrieves the timing for allocating + storage space for a dataset's raw data. + This property is set in the dataset creation property list + plist_id. +

    + The timing setting is returned in fill_time as one of the + following values: + +
         + H5D_ALLOC_TIME_DEFAULT   + + Uses the default allocation time, based on the dataset storage method.
    + See the fill_time description in + H5Pset_alloc_time for + default allocation times for various storage methods. +
    + H5D_ALLOC_TIME_EARLY + + All space is allocated when the dataset is created. +
    + H5D_ALLOC_TIME_INCR   + + Space is allocated incrementally as data is written to the dataset. +
    + H5D_ALLOC_TIME_LATE + + All space is allocated when data is first written to the dataset. +
    +

    Note: +
    H5Pget_alloc_time is designed to work in concert + with the dataset fill value and fill value write time properties, + set with the functions + H5Pget_fill_value and H5Pget_fill_time. +

    Parameters: -
      - - - - - - -
      hid_t idIN: Identifier for the property to query
      const char *nameIN: Name of property to check for
    - +
    +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    H5D_alloc_time_t *alloc_time +
    IN: When to allocate dataset storage space. +
    Returns: -
    Success: a positive value if the property exists in the - property object; zero if the property does not exist -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Pget_size - +
    Name: H5Pget_btree_ratios
    Signature: -
    int H5Pget_size( - hid_t id, - const char *name, - size_t *size - ) - +
    herr_t H5Pget_btree_ratios(hid_t plist, + double *left, + double *middle, + double *right + )
    Purpose: -
    Queries the size of a property value in bytes. - +
    Gets B-tree split ratios for a dataset transfer property list.
    Description: -
    H5Pget_size retrieves the size of a - property's value in bytes. This function operates on both - poperty lists and property classes - -

    - Zero-sized properties are allowed and return 0. - - -

    Parameters: -
      - - - - - - - - - -
      hid_t idIN: Identifier of property object to query
      const char *nameIN: Name of property to query
      size_t *sizeOUT: Size of property in bytes
    - +
    H5Pget_btree_ratios returns the B-tree split ratios + for a dataset transfer property list. +

    + The B-tree split ratios are returned through the non-NULL + arguments left, middle, and right, + as set by the H5Pset_btree_ratios function. +

    Parameters: +
    +
    hid_t plist +
    IN: The dataset transfer property list identifier. +
    double left +
    OUT: The B-tree split ratio for left-most nodes. +
    double right +
    OUT: The B-tree split ratio for right-most nodes and lone nodes. +
    double middle +
    OUT: The B-tree split ratio for all other nodes. +
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Pget_nprops +
    Name: H5Pget_buffer +
    Signature: +
    hsize_t H5Pget_buffer(hid_t plist, + void **tconv, + void **bkg + ) +
    Purpose: +
    Reads buffer settings. +
    Description: +
    H5Pget_buffer reads values previously set + with H5Pset_buffer. +
    Parameters: +
    +
    hid_t plist +
    IN: Identifier for the dataset transfer property list. +
    void **tconv +
    OUT: Address of the pointer to application-allocated + type conversion buffer. +
    void **bkg +
    OUT: Address of the pointer to application-allocated + background buffer. +
    +
    Returns: +
    Returns buffer size, in bytes, if successful; + otherwise 0 on failure. +
    Non-C API(s): +
    + +
    + + +
    +
    +
    Name: H5Pget_cache
    Signature: -
    int H5Pget_nprops( - hid_t id, - size_t *nprops - ) +
    herr_t H5Pget_cache(hid_t plist_id, + int *mdc_nelmts, + int *rdcc_nelmts, + size_t *rdcc_nbytes, + double *rdcc_w0 + ) +
    Purpose: +
    Queries the meta data cache and raw data chunk cache parameters. +
    Description: +
    H5Pget_cache retrieves the maximum possible + number of elements in the meta + data cache and raw data chunk cache, the maximum possible number of + bytes in the raw data chunk cache, and the preemption policy value. +

    + Any (or all) arguments may be null pointers, in which case the + corresponding datum is not returned. +

    Parameters: +
    +
    hid_t plist_id +
    IN: Identifier of the file access property list. +
    int *mdc_nelmts +
    IN/OUT: Number of elements (objects) in the meta data cache. +
    int *rdcc_nelmts +
    IN/OUT: Number of elements (objects) in the raw data chunk cache. +
    size_t *rdcc_nbytes +
    IN/OUT: Total size of the raw data chunk cache, in bytes. +
    double *rdcc_w0 +
    IN/OUT: Preemption policy. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + + +
    +
    +
    Name: H5Pget_chunk +
    Signature: +
    int H5Pget_chunk(hid_t plist, + int max_ndims, + hsize_t * dims + )
    Purpose: -
    Queries number of properties in property list or class. +
    Retrieves the size of chunks for the raw data of a chunked layout dataset.
    Description: -
    H5Pget_nprops retrieves the number of properties in a - property list or class. - If a property class identifier is given, the number of registered - properties in the class is returned in nprops. - If a property list identifier is given, the current number of - properties in the list is returned in nprops. - +
    H5Pget_chunk retrieves the size of chunks for the + raw data of a chunked layout dataset. + This function is only valid for dataset creation property lists. + At most, max_ndims elements of dims + will be initialized.
    Parameters: -
      - - - - - - -
      hid_t idIN: Identifier of property object to query
      size_t *npropsOUT: Number of properties in object
    - +
    +
    hid_t plist +
    IN: Identifier of property list to query. +
    int max_ndims +
    IN: Size of the dims array. +
    hsize_t * dims +
    OUT: Array to store the chunk dimensions. +
    Returns: -
    Success: a non-negative value -
    Failure: a negative value +
    Returns chunk dimensionality successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    -
    Non-C APIs: -
    - + + +
    +
    +
    Name: H5Pget_class +
    Signature: +
    H5P_class_t H5Pget_class(hid_t plist + ) +
    Purpose: +
    Returns the property list class for a property list. +
    Description: +
    H5Pget_class returns the property list class for the + property list identified by the plist parameter. + Valid property list classes are defined in the description of + H5Pcreate. +
    Parameters: +
    +
    hid_t plist +
    IN: Identifier of property list to query. +
    +
    Returns: +
    Returns a property list class if successful. + Otherwise returns H5P_NO_CLASS (-1). +
    Non-C API(s): +
    +
    @@ -1781,566 +1683,419 @@ facilitate moving easily between them.
    - +
    -
    Name: H5Pisa_class - +
    Name: H5Pget_driver
    Signature: -
    htri_t H5Pisa_class( - hid_t plist, - hid_t pclass - ) - +
    hid_t H5Pget_driver( + hid_t plist_id + )
    Purpose: -
    Determines whether a property list is a member of a class. - +
    Returns low-lever driver identifier.
    Description: -
    H5Pisa_class checks to determine whether a property list - is a member of the specified class. - -
    Parameters: -
      - - - - - - -
      hid_t plistIN: Identifier of the property list
      hid_t pclassIN: Identifier of the property class
    - -
    Returns: -
    Success: TRUE (positive) if equal; FALSE (zero) if unequal -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    H5Pget_driver returns the identifier of the + low-level file driver associated with the file access property list + or data transfer property list plist_id. +

    + Valid driver identifiers with the standard HDF5 library distribution + include the following: + 

    +           H5FD_CORE
+           H5FD_DPSS
+           H5FD_FAMILY
+           H5FD_GASS
+           H5FD_LOG
+           H5FD_MPIO
+           H5FD_MULTI
+           H5FD_SEC2
+           H5FD_STDIO
+           H5FD_STREAM
    + If a user defines and registers custom drivers or + if additional drivers are defined in an HDF5 distribution, + this list will be longer. +

    + The returned driver identifier is only valid as long as the + file driver remains registered. +

    Parameters: +
    +
    hid_t plist_id +
    IN: File access or data transfer property list identifier. +
    +
    Returns: +
    Returns a valid low-level driver identifier if successful. + Otherwise returns a negative value. +
    Non-C API(s): +
    +
    - - + +
    Returns a pointer to the struct containing + low-level driver information. + Otherwise returns NULL. +

    + NULL is also returned if no driver-specific properties + have been registered. + No error is pushed on the stack in this case. +

    Non-C API(s): +
    + +
    +--> + - +
    -
    Name: H5Pequal - +
    Name: H5Pget_dxpl_mpio
    Signature: -
    htri_t H5Pequal( - hid_t id1, - hid_t id2 - ) - +
    herr_t H5Pget_dxpl_mpio( + hid_t dxpl_id, + H5FD_mpio_xfer_t *xfer_mode + )
    Purpose: -
    Compares two property lists or classes for equality. - +
    Returns the data transfer mode.
    Description: -
    H5Pequal compares two property lists or classes - to determine whether they are equal to one another. - -

    - Either both id1 and id2 must be - property lists or both must be classes; comparing a list to a - class is an error. - +

    H5Pget_dxpl_mpio queries the data transfer mode + currently set in the data transfer property list dxpl_id. +

    + Upon return, xfer_mode contains the data transfer mode, + if it is non-null. +

    + H5Pget_dxpl_mpio is not a collective function.

    Parameters: -
      - - - - - - -
      hid_t id1IN: First property object to be compared
      hid_t id2IN: Second property object to be compared
    - +
    +
    hid_t dxpl_id +
    IN: Data transfer property list identifier. +
    H5FD_mpio_xfer_t *xfer_mode +
    OUT: Data transfer mode. +
    Returns: -
    Success: TRUE (positive) if equal; FALSE (zero) if unequal -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Piterate - +
    Name: H5Pget_dxpl_multi +
    Signature: +
    herr_t H5Pget_dxpl_multi( + hid_t dxpl_id, + const hid_t *memb_dxpl + ) +
    +
    Purpose: -
    Iterates over properties in a property class or list. +
    Returns multi-file data transfer property list information. +
    Description: +
    H5Pget_dxpl_multi returns the data transfer property list + information for the multi-file driver. +
    Parameters: +
    +
    hid_t dxpl_id, +
    IN: Data transfer property list identifier. +
    const hid_t *memb_dxpl +
    OUT: Array of data access property lists. +
    +
    Returns: +
    Returns a non-negative value if successful. + Otherwise returns a negative value. + + +
    + + +
    +
    +
    Name: H5Pget_edc_check
    Signature: -
    int H5Piterate( - hid_t id, - int * idx, - H5P_iterate_t iter_func, - void * iter_data - ) - +
    H5Z_EDC_t H5Pget_edc_check(hid_t plist) +
    Purpose: +
    Determines whether error-detection is enabled for dataset reads.
    Description: -

    H5Piterate iterates over the properties in the - property object specified in id, which may be either a - property list or a property class, performing a specified - operation on each property in turn. - -

    - For each property in the object, iter_func and - the additional information specified below are passed to the - H5P_iterate_t operator function. - - (NOTE: iter_func was changed to - H5P_iterate_t in the preceding sentence. - Is this correct?) - -

    - The iteration begins with the idx-th property in - the object; the next element to be processed by the operator - is returned in idx. - If idx is NULL, the iterator starts at the first - property; since no stopping point is returned in this case, - the iterator cannot be restarted if one of the calls to its - operator returns non-zero. -

    - - The prototype for the H5P_iterate_t operator is - as follows: -
      -
      typedef herr_t (*H5P_iterate_t)( - hid_t id, - const char *>name, - void *iter_data - ) -
    - The operation receives the property list or class identifier for - the object being iterated over, id, - the name of the current property within the object, name, - and the pointer to the operator data passed in to - H5Piterate, iter_data. -

    - - The valid return values from an operator are as follows: -
      - - - - - - - - - -
      ZeroCauses the iterator to continue, returning zero when all - properties have been processed
      PositiveCauses the iterator to immediately return that positive - value, indicating short-circuit success. The iterator can - be restarted at the index of the next property
      NegativeCauses the iterator to immediately return that value, - indicating failure. The iterator can be restarted at the - index of the next property
    - -

    - H5Piterate assumes that the properties in the object - identified by id remain unchanged through the iteration. - If the membership changes during the iteration, the function's behavior - is undefined. - +

    H5Pget_edc_check queries the dataset transfer property + list plist to determine whether error detection + is enabled for data read operations.
    Parameters: -
      - - - - - - - - - - - - -
      hid_t idIN: Identifier of property object to iterate over
      int * idxIN/OUT: Index of the property to begin with
      H5P_iterate_t iter_funcIN: Function pointer to function to be called with each - property iterated over
      void * iter_dataIN/OUT: Pointer to iteration data from user
    - -
    Returns: -
    Success: the return value of the last call to - iter_func if it was non-zero; - zero if all properties have been processed -
    Failure: a negative value - - - - +
    +
    hid_t plist +
    IN: Dataset transfer property list identifier. +
    +
    Returns: +
    Returns H5P_ENABLE_EDC or H5P_DISABLE_EDC + if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Pcopy_prop - +
    Name: H5Pget_external
    Signature: -
    herr_t H5Pcopy_prop( - hid_t dst_id, - hid_t src_id, - const char *name - ) - +
    herr_t H5Pget_external(hid_t plist, + int idx, + size_t name_size, + char *name, + off_t *offset, + hsize_t *size + )
    Purpose: -
    Copies a property from one list or class to another. - +
    Returns information about an external file.
    Description: -
    H5Pcopy_prop copies a property from one property - list or class to another. - -

    - If a property is copied from one class to another, all the property - information will be first deleted from the destination class and - then the property information will be copied from the source class - into the destination class. - -

    - If a property is copied from one list to another, the property - will be first deleted from the destination list (generating a call - to the close callback for the property, if one exists) - and then the property is copied from the source list to the - destination list (generating a call to the copy - callback for the property, if one exists). - -

    - If the property does not exist in the class or list, this call is - equivalent to calling H5Pregister or H5Pinsert - (for a class or list, as appropriate) and the create - callback will be called in the case of the property being - copied into a list (if such a callback exists for the property). - +

    H5Pget_external returns information about an external + file. The external file is specified by its index, idx, + which is a number from zero to N-1, where N is the value + returned by H5Pget_external_count. + At most name_size characters are copied into the + name array. If the external file name is + longer than name_size with the null terminator, the + return value is not null terminated (similar to strncpy()). +

    + If name_size is zero or name is the + null pointer, the external file name is not returned. + If offset or size are null pointers + then the corresponding information is not returned.

    Parameters: -
      - - - - - - - - - -
      hid_t dst_idIN: Identifier of the destination property list or - class
      hid_t src_idIN: Identifier of the source property list or class
      const char *nameIN: Name of the property to copy
    - +
    +
    hid_t plist +
    IN: Identifier of a dataset creation property list. +
    int idx +
    IN: External file index. +
    size_t name_size +
    IN: Maximum length of name array. +
    char *name +
    OUT: Name of the external file. +
    off_t *offset +
    OUT: Pointer to a location to return an offset value. +
    hsize_t *size +
    OUT: Pointer to a location to return the size of the + external file data. +
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Premove - +
    Name: H5Pget_external_count
    Signature: -
    herr_t H5Premove(plid, name) - hid_t plid; - const char *name - ) - +
    int H5Pget_external_count(hid_t plist + )
    Purpose: -
    Removes a property from a property list. - +
    Returns the number of external files for a dataset.
    Description: -
    H5Premove removes a property from a property list. - -

    - Both properties which were in existence when the property list - was created (i.e. properties registered with H5Pregister) - and properties added to the list after it was created (i.e. added - with H5Pinsert) may be removed from a property list. - Properties do not need to be removed from a property list before the - list itself is closed; they will be released automatically when - H5Pclose is called. - -

    - If a close callback exists for the removed property, - it will be called before the property is released. - +

    H5Pget_external_count returns the number of external files + for the specified dataset.
    Parameters: -
      - - - - - - -
      hid_t plidIN: Identifier of the property list to modify
      const char *nameIN: Name of property to remove
    - -
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - -
    - - - -
    -
    -
    Name: H5Punregister - -
    Signature: -
    herr_t H5Punregister( - H5P_class_t class, - const char *name - ) - -
    Purpose: -
    Removes a property from a property list class. - -
    Description: -
    H5Punregister removes a property from a - property list class. - -

    - Future property lists created of that class will not contain - this property; - existing property lists containing this property are not affected. - -

    Parameters: -
      - - - - - - -
      H5P_class_t classIN: Property list class from which to remove - permanent property
      const char *nameIN: Name of property to remove
    - +
    +
    hid_t plist +
    IN: Identifier of a dataset creation property list. +
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns the number of external files if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Pclose_list - +
    Name: H5Pget_family_offset
    Signature: -
    herr_t H5Pclose_list( - hid_t plist - ) - +
    herr_t H5Pget_family_offset ( + hid_t fapl_id, + hsize_t *offset + )
    Purpose: -
    Closes a property list. - +
    Retrieves a data offset from the file access property list.
    Description: -
    H5Pclose_list closes a property list. - -

    - If a close callback exists for the property list class, - it is called before the property list is destroyed. - If close callbacks exist for any individual properties - in the property list, they are called after the class - close callback. - +

    H5Pget_family_offset retrieves the value of offset + from the file access property list fapl_id + so that the user application + can retrieve a file handle for low-level access to a particluar member + of a family of files. The file handle is retrieved with a separate call + to H5Fget_vfd_handle + (or, in special circumstances, to H5FDget_vfd_handle; + see Virtual File Layer and List of VFL Functions + in HDF5 Technical Notes). +

    + The data offset returned in offset is the offset + of the data in the HDF5 file that is stored on disk in the selected + member file in a family of files. +

    + Use of this function is only appropriate for an HDF5 file written as a + family of files with the FAMILY file driver.

    Parameters: -
      - - -
      hid_t plist - IN: Property list to close
    - +
    +
    hid_t fapl_id +
    IN: File access property list identifier. +
    hsize_t *offset +
    IN: Offset in bytes within the HDF5 file. +
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns a non-negative value if successful; + otherwise returns a negative value. + +
    - +
    -
    Name: H5Pclose_class - +
    Name: H5Pget_fapl_core
    Signature: -
    herr_t H5Pclose_class( - hid_t class - ) - +
    herr_t H5Pget_fapl_core( + hid_t fapl_id, + size_t *increment, + hbool_t *backing_store + )
    Purpose: -
    Closes an existing property list class. - +
    Queries core file driver properties.
    Description: -
    Removes a property list class from the library. - -

    - Existing property lists of this class will continue to exist, - but new ones are not able to be created. - +

    H5Pget_fapl_core queries the H5FD_CORE + driver properties as set by H5Pset_fapl_core.
    Parameters: -
      - - - -
      hid_t classIN: Property list class to close
    - +
    +
    hid_t fapl_id +
    IN: File access property list identifier. +
    size_t *increment +
    OUT: Size, in bytes, of memory increments. +
    hbool_t *backing_store +
    OUT: Boolean flag indicating whether to write the file + contents to disk when the file is closed. +
    Returns: -
    Success: a non-negative value -
    Failure: a negative value - -
    Non-C APIs: -
    - +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    Non-C API(s): +
    +
    - +
    -
    Name: H5Pget_version +
    Name: H5Pget_fapl_family
    Signature: -
    herr_t H5Pget_version(hid_t plist, - int * super, - int * freelist, - int * stab, - int * shhdr - ) +
    herr_t H5Pget_fapl_family ( + hid_t fapl_id, + hsize_t *memb_size, + hid_t *memb_fapl_id + )
    Purpose: -
    Retrieves the version information of various objects for - a file creation property list. +
    Returns file access property list information.
    Description: -
    H5Pget_version retrieves the version information of various objects - for a file creation property list. Any pointer parameters which are - passed as NULL are not queried. +
    H5Pget_fapl_family returns file access property list + for use with the family driver. + This information is returned through the output parameters.
    Parameters:
    -
    hid_t plist -
    IN: Identifier of the file creation property list. -
    int * super -
    OUT: Pointer to location to return super block version number. -
    int * freelist -
    OUT: Pointer to location to return global freelist version number. -
    int * stab -
    OUT: Pointer to location to return symbol table version number. -
    int * shhdr -
    OUT: Pointer to location to return shared object header version number. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    hsize_t *memb_size +
    OUT: Size in bytes of each file member. +
    hid_t *memb_fapl_id +
    OUT: Identifier of file access property list for each + family member.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_userblock +
    Name: H5Pget_fapl_gass
    Signature: -
    herr_t H5Pset_userblock(hid_t plist, - hsize_t size - ) +
    herr_t H5Pget_fapl_gass( + hid_t fapl_id, + GASS_Info *info + )
    Purpose: -
    Sets user block size. +
    Retrieves GASS information.
    Description: -
    H5Pset_userblock sets the user block size of a - file creation property list. - The default user block size is 0; it may be set to any - power of 2 equal to 512 or greater (512, 1024, 2048, etc.). +
    If the file access property list fapl_id is set + for use of the H5FD_GASS driver, + H5Pget_fapl_gass returns the GASS_Info + object through the info pointer. +

    + The GASS_Info information is copied, so it is valid + only until the file access property list is modified or closed. +

    Note: +
    H5Pget_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + GASS facility of the Globus environment. + For further information, see + http//www.globus.org/.
    Parameters:
    -
    hid_t plist -
    IN: Identifier of property list to modify. -
    hsize_t size -
    IN: Size of the user-block in bytes. +
    hid_t fapl_id, +
    IN: File access property list identifier. +
    GASS_Info *info +
    OUT: Pointer to the GASS information structure.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. + - +
    -
    Name: H5Pget_userblock +
    Name: H5Pget_fapl_mpio
    Signature: -
    herr_t H5Pget_userblock(hid_t plist, - hsize_t * size - ) +
    herr_t H5Pget_fapl_mpio( + hid_t fapl_id, + MPI_Comm *comm, + MPI_Info *info + )
    Purpose: -
    Retrieves the size of a user block. +
    Returns MPI communicator information.
    Description: -
    H5Pget_userblock retrieves the size of a user block - in a file creation property list. +
    If the file access property list is set to the H5FD_MPIO + driver, H5Pget_fapl_mpio returns the MPI communicator and + information through the comm and info + pointers, if those values are non-null. +

    + Neither comm nor info is copied, + so they are valid only until the file access property list + is either modified or closed.

    Parameters:
    -
    hid_t plist -
    IN: Identifier for property list to query. -
    hsize_t * size -
    OUT: Pointer to location to return user-block size. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    MPI_Comm *comm +
    OUT: MPI-2 communicator. +
    MPI_Info *info +
    OUT: MPI-2 info object.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_sizes +
    Name: H5Pget_fapl_mpiposix
    Signature: -
    herr_t H5Pset_sizes(hid_t plist, - size_t sizeof_addr, - size_t sizeof_size - ) +
    herr_t H5Pget_fapl_mpiposix( + hid_t fapl_id, + MPI_Comm *comm + )
    Purpose: -
    Sets the byte size of the offsets and lengths used to address objects - in an HDF5 file. +
    Returns MPI communicator information.
    Description: -
    H5Pset_sizes sets the byte size of the offsets and lengths used to - address objects in an HDF5 file. This function is only valid for - file creation property lists. Passing in a value of 0 for one of the - sizeof parameters retains the current value. The default value - for both values is same as sizeof(hsize_t) in the library - (normally 8 bytes). Valid values currently are 2, 4, - 8 and 16. +
    If the file access property list is set to the H5FD_MPIO + driver, H5Pget_fapl_mpiposix returns + the MPI communicator through the comm + pointer, if those values are non-null. +

    + comm is not copied, so it is valid only + until the file access property list is either modified or closed.

    Parameters:
    -
    hid_t plist -
    IN: Identifier of property list to modify. -
    size_t sizeof_addr -
    IN: Size of an object offset in bytes. -
    size_t sizeof_size -
    IN: Size of an object length in bytes. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    MPI_Comm *comm +
    OUT: MPI-2 communicator.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    - +
    -
    Name: H5Pget_sizes +
    Name: H5Pget_fapl_multi
    Signature: -
    herr_t H5Pget_sizes(hid_t plist, - size_t * sizeof_addr, - size_t * sizeof_size - ) +
    herr_t H5Pget_fapl_multi( + hid_t fapl_id, + const H5FD_mem_t *memb_map, + const hid_t *memb_fapl, + const char **memb_name, + const haddr_t *memb_addr, + hbool_t *relax + )
    Purpose: -
    Retrieves the size of the offsets and lengths used in an HDF5 file. +
    Returns information about the multi-file access property list.
    Description: -
    H5Pget_sizes retrieves the size of the offsets - and lengths used in an HDF5 file. - This function is only valid for file creation property lists. +
    H5Pget_fapl_multi returns information about the + multi-file access property list.
    Parameters:
    -
    hid_t plist -
    IN: Identifier of property list to query. -
    size_t * size -
    OUT: Pointer to location to return offset size in bytes. -
    size_t * size -
    OUT: Pointer to location to return length size in bytes. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    const H5FD_mem_t *memb_map +
    OUT: Maps memory usage types to other memory usage types. +
    const hid_t *memb_fapl +
    OUT: Property list for each memory usage type. +
    const char **memb_name +
    OUT: Name generator for names of member files. +
    const haddr_t *memb_addr +
    OUT: +
    hbool_t *relax +
    OUT: Allows read-only access to incomplete file sets + when TRUE.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_sym_k +
    Name: H5Pget_fapl_srb
    Signature: -
    herr_t H5Pset_sym_k(hid_t plist, - int ik, - int lk - ) +
    herr_t H5Pget_fapl_srb( + hid_t fapl_id, + SRB_Info *info + )
    Purpose: -
    Sets the size of parameters used to control the symbol table nodes. +
    Retrieves SRB information.
    Description: -
    H5Pset_sym_k sets the size of parameters used to - control the symbol table nodes. This function is only valid - for file creation property lists. Passing in a value of 0 for - one of the parameters retains the current value. -

    - ik is one half the rank of a tree that stores a symbol - table for a group. Internal nodes of the symbol table are on - average 75% full. That is, the average rank of the tree is - 1.5 times the value of ik. -

    - lk is one half of the number of symbols that can - be stored in a symbol table node. A symbol table node is the - leaf of a symbol table tree which is used to store a group. - When symbols are inserted randomly into a group, the group's - symbol table nodes are 75% full on average. That is, they - contain 1.5 times the number of symbols specified by - lk. +

    If the file access property list fapl_id is set + for use of the H5FD_SRB driver, + H5Pget_fapl_srb returns the SRB_Info + object through the info pointer. +

    + The SRB_Info information is copied, so it is valid + only until the file access property list is modified or closed. +

    Note: +
    H5Pset_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + Storage Resource Broker (SRB). For further information, see + http//www.npaci.edu/Research/DI/srb/.
    Parameters:
    -
    hid_t plist -
    IN: Identifier for property list to query. -
    int ik -
    IN: Symbol table tree rank. -
    int lk -
    IN: Symbol table node size. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    SRB_Info *info +
    OUT: Pointer to the SRB information structure.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. + - +
    -
    Name: H5Pget_sym_k +
    Name: H5Pget_fapl_stream
    Signature: -
    herr_t H5Pget_sym_k(hid_t plist, - int * ik, - int * lk - ) +
    herr_t H5Pget_fapl_stream( + hid_t fapl_id, + H5FD_stream_fapl_t *fapl + )
    Purpose: -
    Retrieves the size of the symbol table B-tree 1/2 rank - and the symbol table leaf node 1/2 size. +
    Returns the streaming I/O driver settings.
    Description: -
    H5Pget_sym_k retrieves the size of the - symbol table B-tree 1/2 rank and the symbol table leaf - node 1/2 size. This function is only valid for file creation - property lists. If a parameter valued is set to NULL, that - parameter is not retrieved. See the description for - H5Pset_sym_k for more - information. -
    Parameters: -
    -
    hid_t plist -
    IN: Property list to query. -
    int * ik -
    OUT: Pointer to location to return the symbol table's B-tree 1/2 rank. -
    int * size -
    OUT: Pointer to location to return the symbol table's leaf node 1/2 size. +
    H5Pget_fapl_stream returns the file access properties + set for the use of the streaming I/O driver. +

    + H5Pset_fapl_stream and H5Pget_fapl_stream + are not intended for use in a parallel environment. +

    Parameters: +
    +
    hid_t fapl_id +
    IN: File access property list identifier. +
    H5FD_stream_fapl_t *fapl +
    OUT: The streaming I/O file access property list.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. + - +
    -
    Name: H5Pset_istore_k -
    Signature: -
    herr_t H5Pset_istore_k(hid_t plist, - int ik - ) -
    Purpose: -
    Sets the size of the parameter used to control the - B-trees for indexing chunked datasets. -
    Description: -
    H5Pset_istore_k sets the size of the parameter - used to control the B-trees for indexing chunked datasets. - This function is only valid for file creation property lists. -

    - 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: +
    Name: H5Pget_fclose_degree +
    Signature: +
    herr_t H5Pget_fclose_degree(hid_t fapl_id, + H5F_close_degree_t fc_degree) +
    Purpose: +
    Returns the file close degree. +
    Description: +
    H5Pget_fclose_degree returns the current setting of the file + close degree property fc_degree in the file access property list + fapl_id.  +

    The value of fc_degree determines how aggressively H5Fclose + deals with objects within a file that remain open when H5Fclose + is called to close that file.  fc_degree can have any one of + four valid values as described above in H5Pset_fclose_degree. +

    Parameters:
    -
    hid_t plist -
    IN: Identifier of property list to query. -
    int ik -
    IN: 1/2 rank of chunked storage B-tree. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    H5F_close_degree_t fc_degree +
    OUT: Pointer to a location to which to return the file close degree + property, the value of fc_degree.
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns: +
    Returns a non-negative value if successful. Otherwise returns a negative + value.
    Non-C API(s): -
    -
    - +
    -
    Name: H5Pget_istore_k +
    Name: H5Pget_fill_time
    Signature: -
    herr_t H5Pget_istore_k(hid_t plist, - int * ik +
    herr_t H5Pget_fill_time(hid_t plist_id, + H5D_fill_time_t *fill_time )
    Purpose: -
    Queries the 1/2 rank of an indexed storage B-tree. +
    Retrieves the time when fill value are written to a dataset.
    Description: -
    H5Pget_istore_k queries the 1/2 rank of - an indexed storage B-tree. - The argument ik may be the null pointer (NULL). - This function is only valid for file creation property lists. -

    - See H5Pset_istore_k for details. +

    H5Pget_fill_time examines the dataset creation + property list plist_id to determine when fill values + are to be written to a dataset. +

    + Valid values returned in fill_time are as follows: + +
         + H5D_FILL_TIME_IFSET   + + Fill values are written to the dataset when storage space is allocated + only if there is a user-defined fill value, i.e., one set with + H5Pset_fill_value. +   (Default) +
      + H5D_FILL_TIME_ALLOC   + + Fill values are written to the dataset when storage space is allocated. +
      + H5D_FILL_TIME_NEVER + + Fill values are never written to the dataset. +
    +

    Note: +
    H5Pget_fill_time is designed to work in coordination + with the dataset fill value and + dataset storage allocation time properties, retrieved with the functions + H5Pget_fill_value and H5Pget_alloc_time. +

    Parameters:
    -
    hid_t plist -
    IN: Identifier of property list to query. -
    int * ik -
    OUT: Pointer to location to return the chunked storage B-tree 1/2 rank. +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    H5D_fill_time_t *fill_time +
    OUT: Setting for the timing of writing fill values to the dataset.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_layout +
    Name: H5Pget_fill_value
    Signature: -
    herr_t H5Pset_layout(hid_t plist, - H5D_layout_t layout - ) +
    herr_t H5Pget_fill_value(hid_t plist_id, + hid_t type_id, + void *value + )
    Purpose: -
    Sets the type of storage used to store the raw data for a dataset. +
    Retrieves a dataset fill value.
    Description: -
    H5Pset_layout sets the type of storage used to store the - raw data for a dataset. - This function is only valid for dataset creation property lists. +
    H5Pget_fill_value returns the dataset + fill value defined in the dataset creation property list + plist_id.

    - Valid values for layout are: -

      -
      H5D_COMPACT -
      Store raw data in the dataset object header in file. - This should only be used for very small amounts of raw - data. - The current limit is approximately 64K (HDF5 Release 1.6). -
      H5D_CONTIGUOUS -
      Store raw data separately from the object header in one - large chunk in the file. -
      H5D_CHUNKED -
      Store raw data separately from the object header as - chunks of data in separate locations in the file. -
    + The fill value is returned through the value + pointer and will be converted to the datatype specified + by type_id. + This datatype may differ from the + fill value datatype in the property list, + but the HDF5 library must be able to convert between the + two datatypes. +

    + If the fill value is undefined, + i.e., set to NULL in the property list, + H5Pget_fill_value will return an error. + H5Pfill_value_defined should be used to + check for this condition before + H5Pget_fill_value is called. +

    + Memory must be allocated by the calling application. +

    Note: +
    H5Pget_fill_value is designed to coordinate + with the dataset storage allocation time and + fill value write time properties, which can be retrieved + with the functions H5Pget_alloc_time + and H5Pget_fill_time, respectively. +

    Parameters:
    -
    hid_t plist -
    IN: Identifier of property list to query. -
    H5D_layout_t layout -
    IN: Type of storage layout for raw data. +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    hid_t type_id, +
    IN: Datatype identifier for the value passed + via value. +
    void *value +
    OUT: Pointer to buffer to contain the returned fill value.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_layout +
    Name: H5Pget_filter
    Signature: -
    H5D_layout_t H5Pget_layout(hid_t plist) +
    H5Z_filter_t H5Pget_filter(hid_t plist, + int filter_number, + unsigned int *flags, + size_t *cd_nelmts, + unsigned int *cd_values, + size_t namelen, + char name[] + )
    Purpose: -
    Returns the layout of the raw data for a dataset. +
    Returns information about a filter in a pipeline.
    Description: -
    H5Pget_layout returns the layout of the raw data for - a dataset. This function is only valid for dataset creation - property lists. - +
    H5Pget_filter returns information about a + filter, specified by its filter number, in a filter pipeline, + specified by the property list with which it is associated. +

    + If plist is a dataset creation property list, + the pipeline is a permanent filter pipeline; + if plist is a dataset transfer property list, + the pipeline is a transient filter pipeline. +

    + On input, cd_nelmts indicates the number of entries + in the cd_values array, as allocated by the caller; + on return,cd_nelmts contains the number of values + defined by the filter. +

    + filter_number is a value between zero and + N-1, as described in + H5Pget_nfilters. + The function will return a negative value if the filter number + is out of range. +

    + If name is a pointer to an array of at least + namelen bytes, the filter name will be copied + into that array. The name will be null terminated if + namelen is large enough. The filter name returned + will be the name appearing in the file, the name registered + for the filter, or an empty string. +

    + The structure of the flags argument is discussed + in H5Pset_filter. +

    Note: +
    This function currently supports only the permanent filter + pipeline; plist must be a dataset creation property + list.
    Parameters:
    hid_t plist -
    IN: Identifier for property list to query. -
    +
    IN: Property list identifier. +
    int filter_number +
    IN: Sequence number within the filter pipeline of + the filter for which information is sought. +
    unsigned int *flags +
    OUT: Bit vector specifying certain general properties + of the filter. +
    size_t *cd_nelmts +
    IN/OUT: Number of elements in cd_values. +
    unsigned int *cd_values +
    OUT: Auxiliary data for the filter. +
    size_t namelen +
    IN: Anticipated number of characters in name. +
    char name[] +
    OUT: Name of the filter. +
    Returns: -
    Returns the layout type (a non-negative value) - of a dataset creation property list if successful. - Valid return values are: -
      -
      H5D_COMPACT -
      Raw data is stored in the object header in the file. -
      H5D_CONTIGUOUS -
      Raw data is stored separately from the object header in - one contiguous chunk in the file. -
      H5D_CHUNKED -
      Raw data is stored separately from the object header in - chunks in separate locations in the file. -
    -

    - Otherwise, returns a negative value indicating faliure. +

    Returns the filter identifier if successful: +
    + + + + + +
    + H5Z_FILTER_DEFLATE + + Data compression filter, employing the gzip algorithm +
    + H5Z_FILTER_SHUFFLE + + Data shuffling filter +
    + H5Z_FILTER_FLETCHER32   + + Error detection filter, employing the Fletcher32 checksum algorithm +
    + H5Z_FILTER_SZIP + + Data compression filter, employing the SZIP algorithm +
    +
    + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_chunk +
    Name: H5Pget_filter_by_id
    Signature: -
    herr_t H5Pset_chunk(hid_t plist, - int ndims, - const hsize_t * dim - ) +
    herr_t H5Pget_filter_by_id( + hid_t plist_id, + H5Z_filter_t filter, + unsigned int *flags, + size_t *cd_nelmts, + unsigned int cd_values[], + size_t namelen, + char name[] + )
    Purpose: -
    Sets the size of the chunks used to store a chunked layout dataset. +
    Returns information about the specified filter.
    Description: -
    H5Pset_chunk sets the size of the chunks used to - store a chunked layout dataset. This function is only valid - for dataset creation property lists. - The ndims parameter currently must be the same size - as the rank of the dataset. The values of the dim - array define the size of the chunks to store the dataset's raw data. - As a side-effect, the layout of the dataset is changed to - H5D_CHUNKED, if it is not already. -
    Parameters: +
    H5Pget_filter_by_id returns information about the + filter specified in filter, a filter identifier. +

    + plist_id must identify a dataset creation property list + and filter will be in a permanent filter pipeline. +

    + The filter and flags parameters are used + in the same manner as described in the discussion of + H5Pset_filter. +

    + Aside from the fact that they are used for output, the + parameters cd_nelmts and cd_values[] are + used in the same manner as described in the discussion + of H5Pset_filter. + On input, the cd_nelmts parameter indicates the + number of entries in the cd_values[] array + allocated by the calling program; on exit it contains the + number of values defined by the filter. +

    + On input, the name_len parameter indicates the + number of characters allocated for the filter name + by the calling program in the array name[]. + On exit it contains the length in characters of name of the filter. + On exit name[] contains the name of the filter + with one character of the name in each element of the array. +

    + If the filter specified in filter is not + set for the property list, an error will be returned + and H5Pget_filter_by_id will fail. +

    Parameters:
    -
    hid_t plist -
    IN: Identifier for property list to query. -
    int ndims -
    IN: The number of dimensions of each chunk. -
    const hsize_t * dim -
    IN: An array containing the size of each chunk. +
    hid_t plist_id +
    IN: Property list identifier. +
    H5Z_filter_t filter +
    IN: Filter identifier. +
    unsigned int flags +
    OUT: Bit vector specifying certain general properties + of the filter. +
    size_t cd_nelmts +
    IN/OUT: Number of elements in cd_values. +
    const unsigned int cd_values[] +
    OUT: Auxiliary data for the filter. +
    size_t namelen +
    IN/OUT: Length of filter name and + number of elements in name[]. +
    char *name[] +
    OUT: Name of filter.
    -
    Returns: +
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. -
    Non-C API(s): -
    Non-C API(s): +
    - +
    -
    Name: H5Pget_chunk +
    Name: H5Pget_gc_references
    Signature: -
    int H5Pget_chunk(hid_t plist, - int max_ndims, - hsize_t * dims - ) +
    herr_t H5Pget_gc_references(hid_t plist, + unsigned *gc_ref + )
    Purpose: -
    Retrieves the size of chunks for the raw data of a chunked layout dataset. - +
    Returns garbage collecting references setting.
    Description: -
    H5Pget_chunk retrieves the size of chunks for the - raw data of a chunked layout dataset. - This function is only valid for dataset creation property lists. - At most, max_ndims elements of dims - will be initialized. +
    H5Pget_gc_references returns the current setting + for the garbage collection references property from + the specified file access property list. + The garbage collection references property is set + by H5Pset_gc_references.
    Parameters:
    hid_t plist -
    IN: Identifier of property list to query. -
    int max_ndims -
    IN: Size of the dims array. -
    hsize_t * dims -
    OUT: Array to store the chunk dimensions. +
    IN: File access property list identifier. +
    unsigned gc_ref +
    OUT: Flag returning the state of reference garbage collection. + A returned value of 1 indicates that + garbage collection is on while + 0 indicates that garbage collection is off.
    Returns: -
    Returns chunk dimensionality successful; +
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_alignment +
    Name: H5Pget_hyper_cache
    Signature: -
    herr_t H5Pset_alignment(hid_t plist, - hsize_t threshold, - hsize_t alignment +
    herr_t H5Pget_hyper_cache(hid_t plist, + unsigned *cache, + unsigned *limit )
    Purpose: -
    Sets alignment properties of a file access property list. -
    Description: -
    H5Pset_alignment sets the alignment properties - of a file access property list - so that any file object greater than or equal in size to - threshold bytes will be aligned on an address - which is a multiple of alignment. The addresses - are relative to the end of the user block; the alignment is - calculated by subtracting the user block size from the - absolute file address and then adjusting the address to be a - multiple of alignment. +
    [NOTE: + + This function is deprecated in HDF5 Release 1.6 + and will eventually be removed from the HDF5 distribution. + It is provided in this release only to enable backward compatibility + with HDF5 Releases 1.4.x + and is enabled only if the HDF5 library is configured + with the flag H5_WANT_H5_V1_4_COMPAT; + the function is not enabled in the binaries distributed by NCSA. + ]

    - Default values for threshold and - alignment are one, implying - no alignment. Generally the default values will result in - the best performance for single-process access to the file. - For MPI-IO and other parallel systems, choose an alignment - which is a multiple of the disk block size. + Returns information regarding the caching of hyperslab blocks during I/O. +

    Description: +
    Given a dataset transfer property list, H5Pget_hyper_cache + returns instructions regarding the caching of hyperslab blocks during I/O. + These parameters are set with the H5Pset_hyper_cache function.
    Parameters:
    hid_t plist -
    IN: Identifier for a file access property list. -
    hsize_t threshold -
    IN: Threshold value. - Must be non-negative. - Note that setting the threshold value to 0 (zero) has - the effect of a special case, forcing everything - to be aligned. -
    hsize_t alignment -
    IN: Alignment value. - Must be a positive value. +
    IN: Dataset transfer property list identifier. +
    unsigned *cache +
    OUT: A flag indicating whether caching is + set to on (1) or off (0). +
    unsigned *limit +
    OUT: Maximum size of the hyperslab block to cache. + 0 (zero) indicates no limit.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_alignment +
    Name: H5Pget_hyper_vector_size
    Signature: -
    herr_t H5Pget_alignment(hid_t plist, - hsize_t *threshold, - hsize_t *alignment +
    herr_t H5Pget_hyper_vector_size(hid_t dxpl_id, + size_t *vector_size )
    Purpose: -
    Retrieves the current settings for alignment properties from a - file access property list. +
    Retrieves number of I/O vectors to be read/written in hyperslab I/O.
    Description: -
    H5Pget_alignment retrieves the current settings for - alignment properties from a file access property list. - The threshold and/or alignment pointers - may be null pointers (NULL). +
    H5Pset_hyper_vector_size retrieves the number of + I/O vectors to be accumulated in memory before being issued + to the lower levels of the HDF5 library for reading or writing the + actual data. +

    + The number of I/O vectors set in the dataset transfer property list + dxpl_id is returned in vector_size. + Unless the default value is in use, vector_size + was previously set with a call to + H5Pset_hyper_vector_size.

    Parameters:
    -
    hid_t plist -
    IN: Identifier of a file access property list. -
    hsize_t *threshold -
    OUT: Pointer to location of return threshold value. -
    hsize_t *alignment -
    OUT: Pointer to location of return alignment value. +
    hid_t dxpl_id +
    IN: Dataset transfer property list identifier. +
    size_t *vector_size +
    OUT: Number of I/O vectors to accumulate in memory for I/O operations.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. + +
    Non-C API(s): -
    - +
    -
    Name: H5Pset_external +
    Name: H5Pget_istore_k
    Signature: -
    herr_t H5Pset_external(hid_t plist, - const char *name, - off_t offset, - hsize_t size - ) +
    herr_t H5Pget_istore_k(hid_t plist, + int * ik + )
    Purpose: -
    Adds an external file to the list of external files. +
    Queries the 1/2 rank of an indexed storage B-tree.
    Description: -
    H5Pset_external adds an external file to the - list of external files. -

    - If a dataset is split across multiple files then the files - should be defined in order. The total size of the dataset is - the sum of the size arguments for all the external files. If - the total size is larger than the size of a dataset then the - dataset can be extended (provided the data space also allows - the extending). -

    - The size argument specifies number of bytes reserved - for data in the external file. - If size is set to H5F_UNLIMITED, the - external file can be of unlimited size and no more files can be added to - the external files list. +

    H5Pget_istore_k queries the 1/2 rank of + an indexed storage B-tree. + The argument ik may be the null pointer (NULL). + This function is only valid for file creation property lists. +

    + See H5Pset_istore_k for details.

    Parameters:
    hid_t plist -
    IN: Identifier of a dataset creation property list. -
    const char *name -
    IN: Name of an external file. -
    off_t offset -
    IN: Offset, in bytes, from the beginning of the file - to the location in the file where the data starts. -
    hsize_t size -
    IN: Number of bytes reserved in the file for the data. +
    IN: Identifier of property list to query. +
    int * ik +
    OUT: Pointer to location to return the chunked storage B-tree 1/2 rank.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_external_count +
    Name: H5Pget_layout
    Signature: -
    int H5Pget_external_count(hid_t plist - ) +
    H5D_layout_t H5Pget_layout(hid_t plist)
    Purpose: -
    Returns the number of external files for a dataset. +
    Returns the layout of the raw data for a dataset.
    Description: -
    H5Pget_external_count returns the number of external files - for the specified dataset. +
    H5Pget_layout returns the layout of the raw data for + a dataset. This function is only valid for dataset creation + property lists. +
    Parameters:
    hid_t plist -
    IN: Identifier of a dataset creation property list. +
    IN: Identifier for property list to query.
    Returns: -
    Returns the number of external files if successful; - otherwise returns a negative value. +
    Returns the layout type (a non-negative value) + of a dataset creation property list if successful. + Valid return values are: +
      +
      H5D_COMPACT +
      Raw data is stored in the object header in the file. +
      H5D_CONTIGUOUS +
      Raw data is stored separately from the object header in + one contiguous chunk in the file. +
      H5D_CHUNKED +
      Raw data is stored separately from the object header in + chunks in separate locations in the file. +
    +

    + Otherwise, returns a negative value indicating faliure.

    Non-C API(s): -
    - +
    -
    Name: H5Pget_external +
    Name: H5Pget_meta_block_size
    Signature: -
    herr_t H5Pget_external(hid_t plist, - int idx, - size_t name_size, - char *name, - off_t *offset, - hsize_t *size +
    herr_t H5Pget_meta_block_size( + hid_t fapl_id, + hsize_t *size )
    Purpose: -
    Returns information about an external file. +
    Returns the current metadata block size setting.
    Description: -
    H5Pget_external returns information about an external - file. The external file is specified by its index, idx, - which is a number from zero to N-1, where N is the value - returned by H5Pget_external_count. - At most name_size characters are copied into the - name array. If the external file name is - longer than name_size with the null terminator, the - return value is not null terminated (similar to strncpy()). +
    H5Pget_meta_block_size returns the current + minimum size, in bytes, of new metadata block allocations. + This setting is retrieved from the file access property list + fapl_id.

    - If name_size is zero or name is the - null pointer, the external file name is not returned. - If offset or size are null pointers - then the corresponding information is not returned. + This value is set by + H5Pset_meta_block_size + and is retrieved from the file access property list + fapl_id.

    Parameters:
    -
    hid_t plist -
    IN: Identifier of a dataset creation property list. -
    int idx -
    IN: External file index. -
    size_t name_size -
    IN: Maximum length of name array. -
    char *name -
    OUT: Name of the external file. -
    off_t *offset -
    OUT: Pointer to a location to return an offset value. -
    hsize_t *size -
    OUT: Pointer to a location to return the size of the - external file data. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    hsize_t *size +
    OUT: Minimum size, in bytes, of metadata block allocations.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_fill_value +
    Name: H5Pget_multi_type
    Signature: -
    herr_t H5Pset_fill_value(hid_t plist_id, - hid_t type_id, - const void *value +
    herr_t H5Pset_multi_type ( + hid_t fapl_id, + H5FD_mem_t *type )
    Purpose: -
    Sets the fill value for a dataset. +
    Retrieves data type property for MULTI driver.
    Description: -
    H5Pset_fill_value sets the fill value for - a dataset in the dataset creation property list. -

    - value is interpreted as being of datatype - type_id. This datatype may differ from that of - the dataset, but the HDF5 library must be able to convert - value to the dataset datatype when the dataset - is created. -

    - The default fill value is 0 (zero), which is - interpreted according to the actual dataset datatype. -

    - Setting value to NULL indicates - that the fill value is to be undefined. -

    Notes: -
    Applications sometimes write data only to portions of - an allocated dataset. It is often useful in such cases - to fill the unused space with a known - fill value. - This function allows the user application to set that fill value; - the functions - H5Dfill and - H5Pset_fill_time, - respectively, provide the ability - to apply the fill value on demand or - to set up its automatic application. -

    - A fill value should be defined so that it is appropriate for - the application. While the HDF5 default fill value is - 0 (zero), it is often appropriate to use another value. - It might be useful, for example, to use a value that is - known to be impossible for the application to legitimately generate. +

    H5Pget_multi_type retrieves the data type setting from the + file access or data transfer property list fapl_id. + This enables a user application to specifiy the type of data the + application wishes to access so that the application + can retrieve a file handle for low-level access to the particular member + of a set of MULTI files in which that type of data is stored. + The file handle is retrieved with a separate call + to H5Fget_vfd_handle + (or, in special circumstances, to H5FDget_vfd_handle; + see Virtual File Layer and List of VFL Functions + in HDF5 Technical Notes).

    - H5Pset_fill_value is designed to work in - concert with H5Pset_alloc_time and - H5Pset_fill_time. - H5Pset_alloc_time and H5Pset_fill_time - govern the timing of dataset storage allocation and fill value - write operations and can be important in tuning application - performance. + The type of data returned in type will be one of those + listed in the discussion of the type parameter in the the + description of the function + H5Pset_multi_type.

    - See H5Dcreate for - further cross-references. + Use of this function is only appropriate for an HDF5 file written + as a set of files with the MULTI file driver.

    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    hid_t type_id, -
    IN: Datatype of value. -
    const void *value -
    IN: Pointer to buffer containing value to use as fill value. +
    hid_t fapl_id +
    IN: File access property list or data transfer property list identifier. +
    H5FD_mem_t *type +
    OUT: Type of data.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. + - +
    -
    Name: H5Pget_fill_value +
    Name: H5Pget_nfilters
    Signature: -
    herr_t H5Pget_fill_value(hid_t plist_id, - hid_t type_id, - void *value - ) +
    int H5Pget_nfilters(hid_t plist)
    Purpose: -
    Retrieves a dataset fill value. +
    Returns the number of filters in the pipeline.
    Description: -
    H5Pget_fill_value returns the dataset - fill value defined in the dataset creation property list - plist_id. -

    - The fill value is returned through the value - pointer and will be converted to the datatype specified - by type_id. - This datatype may differ from the - fill value datatype in the property list, - but the HDF5 library must be able to convert between the - two datatypes. +

    H5Pget_nfilters returns the number of filters + defined in the filter pipeline associated with the property list + plist.

    - If the fill value is undefined, - i.e., set to NULL in the property list, - H5Pget_fill_value will return an error. - H5Pfill_value_defined should be used to - check for this condition before - H5Pget_fill_value is called. + In each pipeline, the filters are numbered from + 0 through N-1, where N is the value returned + by this function. During output to the file, the filters are + applied in increasing order; during input from the file, they + are applied in decreasing order.

    - Memory must be allocated by the calling application. + H5Pget_nfilters returns the number of filters + in the pipeline, including zero (0) if there + are none.

    Note: -
    H5Pget_fill_value is designed to coordinate - with the dataset storage allocation time and - fill value write time properties, which can be retrieved - with the functions H5Pget_alloc_time - and H5Pget_fill_time, respectively. -

    +

    This function currently supports only the permanent filter + pipeline; plist_id must be a dataset creation + property list.
    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    hid_t type_id, -
    IN: Datatype identifier for the value passed - via value. -
    void *value -
    OUT: Pointer to buffer to contain the returned fill value. +
    hid_t plist +
    IN: Property list identifier.
    Returns: -
    Returns a non-negative value if successful; +
    Returns the number of filters in the pipeline if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pfill_value_defined +
    Name: H5Pget_nprops +
    Signature: -
    herr_t H5Pfill_value_defined(hid_t plist_id, - H5D_fill_value_t *status - ) +
    int H5Pget_nprops( + hid_t id, + size_t *nprops + ) +
    Purpose: -
    Determines whether fill value is defined. +
    Queries number of properties in property list or class. +
    Description: -
    H5Pfill_value_defined determines whether a fill value - is defined in the dataset creation property list plist_id. -

    - Valid values returnrd in status are as follows: - -
         - H5D_FILL_VALUE_UNDEFINED - - Fill value is undefined. -
    - H5D_FILL_VALUE_DEFAULT - - Fill value is the library default. -
    - H5D_FILL_VALUE_USER_DEFINED   - - Fill value is defined by the application. -
    -

    Note: -
    H5Pfill_value_defined is designed for use in - concert with the dataset fill value properties functions - H5Pget_fill_value and H5Pget_fill_time. -

    - See H5Dcreate for - further cross-references. +

    H5Pget_nprops retrieves the number of properties in a + property list or class. + If a property class identifier is given, the number of registered + properties in the class is returned in nprops. + If a property list identifier is given, the current number of + properties in the list is returned in nprops. + +
    Parameters: +
      + + + + + + +
      hid_t idIN: Identifier of property object to query
      size_t *npropsOUT: Number of properties in object
    + +
    Returns: +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    + +
    + + + +
    +
    +
    Name: H5Pget_preserve +
    Signature: +
    int H5Pget_preserve(hid_t plist) +
    Purpose: +
    Checks status of the dataset transfer property list. +
    Description: +
    H5Pget_preserve checks the status of the + dataset transfer property list.
    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    H5D_fill_value_t *status -
    OUT: Status of fill value in property list. +
    hid_t plist +
    IN: Identifier for the dataset transfer property list.
    Returns: -
    Returns a non-negative value if successful; +
    Returns TRUE or FALSE if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_fill_time +
    Name: H5Pget_sieve_buf_size
    Signature: -
    herr_t H5Pset_fill_time(hid_t plist_id, - H5D_fill_time_t fill_time - ) +
    herr_t H5Pget_sieve_buf_size( + hid_t fapl_id, + hsize_t *size + ) +
    +
    Purpose: -
    Sets the time when fill values are written to a dataset. +
    Returns maximum data sieve buffer size.
    Description: -
    H5Pset_fill_time sets up the timing for writing fill values - to a dataset. - This property is set in the dataset creation property list plist_id. +
    H5Pget_sieve_buf_size retrieves, size, + the current maximum size of the data sieve buffer.

    - Timing is specified in fill_time with one of the following values: - -
         - H5D_FILL_TIME_IFSET   - - Write fill values to the dataset when storage space is allocated - only if there is a user-defined fill value, i.e., one set with - H5Pset_fill_value. -   (Default) -
      - H5D_FILL_TIME_ALLOC - - Write fill values to the dataset when storage space is allocated. -
      - H5D_FILL_TIME_NEVER - - Never write fill values to the dataset. -
    -

    Note: -
    H5Pset_fill_time is designed for coordination - with the dataset fill value and - dataset storage allocation time properties, set with the functions - H5Pset_fill_value and H5Pset_alloc_time. -

    - See H5Dcreate for - further cross-references. + This value is set by + H5Pset_sieve_buf_size + and is retrieved from the file access property list + fapl_id.

    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    H5D_fill_time_t fill_time -
    IN: When to write fill values to a dataset. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    hsize_t *size +
    IN: Maximum size, in bytes, of data sieve buffer.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_fill_time +
    Name: H5Pget_size +
    Signature: -
    herr_t H5Pget_fill_time(hid_t plist_id, - H5D_fill_time_t *fill_time - ) +
    int H5Pget_size( + hid_t id, + const char *name, + size_t *size + ) +
    Purpose: -
    Retrieves the time when fill value are written to a dataset. +
    Queries the size of a property value in bytes. +
    Description: -
    H5Pget_fill_time examines the dataset creation - property list plist_id to determine when fill values - are to be written to a dataset. -

    - Valid values returned in fill_time are as follows: - -
         - H5D_FILL_TIME_IFSET   - - Fill values are written to the dataset when storage space is allocated - only if there is a user-defined fill value, i.e., one set with - H5Pset_fill_value. -   (Default) -
      - H5D_FILL_TIME_ALLOC   - - Fill values are written to the dataset when storage space is allocated. -
      - H5D_FILL_TIME_NEVER - - Fill values are never written to the dataset. -
    -

    Note: -
    H5Pget_fill_time is designed to work in coordination - with the dataset fill value and - dataset storage allocation time properties, retrieved with the functions - H5Pget_fill_value and H5Pget_alloc_time. -

    +

    H5Pget_size retrieves the size of a + property's value in bytes. This function operates on both + poperty lists and property classes + +

    + Zero-sized properties are allowed and return 0. + + +

    Parameters: +
      + + + + + + + + + +
      hid_t idIN: Identifier of property object to query
      const char *nameIN: Name of property to query
      size_t *sizeOUT: Size of property in bytes
    + +
    Returns: +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    + +
    + + + +
    +
    +
    Name: H5Pget_sizes +
    Signature: +
    herr_t H5Pget_sizes(hid_t plist, + size_t * sizeof_addr, + size_t * sizeof_size + ) +
    Purpose: +
    Retrieves the size of the offsets and lengths used in an HDF5 file. +
    Description: +
    H5Pget_sizes retrieves the size of the offsets + and lengths used in an HDF5 file. + This function is only valid for file creation property lists.
    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    H5D_fill_time_t *fill_time -
    OUT: Setting for the timing of writing fill values to the dataset. +
    hid_t plist +
    IN: Identifier of property list to query. +
    size_t * size +
    OUT: Pointer to location to return offset size in bytes. +
    size_t * size +
    OUT: Pointer to location to return length size in bytes.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_alloc_time +
    Name: H5Pget_small_data_block_size
    Signature: -
    herr_t H5Pset_alloc_time(hid_t plist_id, - H5D_alloc_time_t alloc_time +
    herr_t H5Pget_small_data_block_size(hid_t fapl_id, + hsize_t *size )
    Purpose: -
    Sets the timing for storage space allocation. +
    Retrieves the current small data block size setting.
    Description: -
    H5Pset_alloc_time sets up the timing for the allocation of - storage space for a dataset's raw data. - This property is set in the dataset creation property list - plist_id. +
    H5Pget_small_data_block_size retrieves the + current setting for the size of the small data block.

    - Timing is specified in fill_time with one of the - following values: - -
         - H5D_ALLOC_TIME_DEFAULT   - - Allocate dataset storage space at the default time.
    - (Defaults differ by storage method.) -
    - H5D_ALLOC_TIME_EARLY - - Allocate all space when the dataset is created.
    - (Default for compact datasets.) -
    - H5D_ALLOC_TIME_INCR   - - Allocate space incrementally, as data is written to the dataset.
    - (Default for chunked storage datasets.) -
  • Chunked datasets: - Storage space allocation for each chunk is deferred until data - is written to the chunk. -
  • Contiguous datasets: - Incremental storage space allocation for contiguous data - is treated as late allocation. -
  • Compact datasets: - Incremental allocation is not allowed with compact datasets; - H5Pset_alloc_time will return an error. -
    • - H5D_ALLOC_TIME_LATE - - Allocate all space when data is first written to the dataset.
    - (Default for contiguous datasets.) -
    -

    Note: -
    H5Pset_alloc_time is designed to work in concert - with the dataset fill value and fill value write time properties, - set with the functions - H5Pset_fill_value and H5Pset_fill_time. -

    -

    - See H5Dcreate for - further cross-references. + If the returned value is zero (0), the small data + block mechanism has been disabled for the file.

    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    H5D_alloc_time_t alloc_time -
    IN: When to allocate dataset storage space. +
    hid_t fapl_id +
    IN: File access property list identifier . +
    hsize_t *size +
    OUT: Maximum size, in bytes, of the small data block. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise a negative value. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Pget_sym_k +
    Signature: +
    herr_t H5Pget_sym_k(hid_t plist, + int * ik, + int * lk + ) +
    Purpose: +
    Retrieves the size of the symbol table B-tree 1/2 rank + and the symbol table leaf node 1/2 size. +
    Description: +
    H5Pget_sym_k retrieves the size of the + symbol table B-tree 1/2 rank and the symbol table leaf + node 1/2 size. This function is only valid for file creation + property lists. If a parameter valued is set to NULL, that + parameter is not retrieved. See the description for + H5Pset_sym_k for more + information. +
    Parameters: +
    +
    hid_t plist +
    IN: Property list to query. +
    int * ik +
    OUT: Pointer to location to return the symbol table's B-tree 1/2 rank. +
    int * size +
    OUT: Pointer to location to return the symbol table's leaf node 1/2 size.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_alloc_time +
    Name: H5Pget_userblock
    Signature: -
    herr_t H5Pget_alloc_time(hid_t plist_id, - H5D_alloc_time_t *alloc_time +
    herr_t H5Pget_userblock(hid_t plist, + hsize_t * size )
    Purpose: -
    Retrieves the timing for storage space allocation. +
    Retrieves the size of a user block.
    Description: -
    H5Pget_alloc_time retrieves the timing for allocating - storage space for a dataset's raw data. - This property is set in the dataset creation property list - plist_id. -

    - The timing setting is returned in fill_time as one of the - following values: - -
         - H5D_ALLOC_TIME_DEFAULT   - - Uses the default allocation time, based on the dataset storage method.
    - See the fill_time description in - H5Pset_alloc_time for - default allocation times for various storage methods. -
    - H5D_ALLOC_TIME_EARLY - - All space is allocated when the dataset is created. -
    - H5D_ALLOC_TIME_INCR   - - Space is allocated incrementally as data is written to the dataset. -
    - H5D_ALLOC_TIME_LATE - - All space is allocated when data is first written to the dataset. -
    -

    Note: -
    H5Pget_alloc_time is designed to work in concert - with the dataset fill value and fill value write time properties, - set with the functions - H5Pget_fill_value and H5Pget_fill_time. -

    +

    H5Pget_userblock retrieves the size of a user block + in a file creation property list.
    Parameters:
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    H5D_alloc_time_t *alloc_time -
    IN: When to allocate dataset storage space. +
    hid_t plist +
    IN: Identifier for property list to query. +
    hsize_t * size +
    OUT: Pointer to location to return user-block size.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_filter +
    Name: H5Pget_version
    Signature: -
    herr_t H5Pset_filter(hid_t plist, - H5Z_filter_t filter, - unsigned int flags, - size_t cd_nelmts, - const unsigned int cd_values[] - ) +
    herr_t H5Pget_version(hid_t plist, + int * super, + int * freelist, + int * stab, + int * shhdr + )
    Purpose: -
    Adds a filter to the filter pipeline. +
    Retrieves the version information of various objects for + a file creation property list.
    Description: -
    H5Pset_filter adds the specified - filter and corresponding properties to the - end of an output filter pipeline. - If plist is a dataset creation property list, - the filter is added to the permanent filter pipeline; - if plist is a dataset transfer property list, - the filter is added to the transient filter pipeline. -

    - The array cd_values contains - cd_nelmts integers which are auxiliary data - for the filter. The integer values will be stored in the - dataset object header as part of the filter information. -

    - The flags argument is a bit vector with - the following fields specifying certain general properties - of the filter: -

    - - - - - -
    H5Z_FLAG_OPTIONAL  If this bit is set then the filter is - optional. If the filter fails (see below) during an - H5Dwrite operation then the filter is - just excluded from the pipeline for the chunk for which - it failed; the filter will not participate in the - pipeline during an H5Dread of the chunk. - This is commonly used for compression filters: if the - filter result would be larger than the input, then - the compression filter returns failure and the - uncompressed data is stored in the file. If this bit is - clear and a filter fails, then H5Dwrite - or H5Dread also fails. -

    - This flag should not be set for the Fletcher32 checksum - filter as it will bypass the checksum filter without - reporting checksum errors to an application.

    -
    -

    - The filter parameter specifies the filter to be set. - Valid values are as follows: - -

    - - - - - -
    - H5Z_FILTER_DEFLATE - - Data compression filter, employing the gzip algorithm -
    - H5Z_FILTER_SHUFFLE - - Data shuffling filter -
    - H5Z_FILTER_FLETCHER32   - - Error detection filter, employing the Fletcher32 checksum algorithm -
    - H5Z_FILTER_SZIP - - Data compression filter, employing the SZIP algorithm -
    -
    -

    - Also see H5Pset_edc_check and - H5Pset_filter_callback. - -

    Notes: -
    This function currently supports only the permanent filter - pipeline; plist must be a dataset creation - property list. -

    - If multiple filters are set for a property list, they will be - applied to each chunk in the order in which they were set. +

    H5Pget_version retrieves the version information of various objects + for a file creation property list. Any pointer parameters which are + passed as NULL are not queried.
    Parameters:
    hid_t plist -
    IN: Property list identifier. -
    H5Z_filter_t filter -
    IN: Filter to be added to the pipeline. -
    unsigned int flags -
    IN: Bit vector specifying certain general properties - of the filter. -
    size_t cd_nelmts -
    IN: Number of elements in cd_values. -
    const unsigned int cd_values[] -
    IN: Auxiliary data for the filter. +
    IN: Identifier of the file creation property list. +
    int * super +
    OUT: Pointer to location to return super block version number. +
    int * freelist +
    OUT: Pointer to location to return global freelist version number. +
    int * stab +
    OUT: Pointer to location to return symbol table version number. +
    int * shhdr +
    OUT: Pointer to location to return shared object header version number.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - -
    -
    -
    Name: H5Pall_filters_avail -
    Signature: -
    htri_t H5Pall_filters_avail(hid_t dcpl_id) -
    Purpose: -
    Verifies that all required filters are available. -
    Description: -
    H5Pall_filters_avail verifies that all of the filters - set in the dataset creation property list dcpl_id are - currently available. -
    Parameters: -
    -
    hid_t dcpl_id -
    IN: Dataset creation property list identifier. -
    -
    Returns: -
    Returns TRUE if all filters are available - and FALSE if one or more is not currently available.
    - Returns FAIL, a negative value, on error. - -
    - - - +
    -
    Name: H5Pget_nfilters +
    Name: H5Pget_vlen_mem_manager
    Signature: -
    int H5Pget_nfilters(hid_t plist) +
    herr_t H5Pget_vlen_mem_manager(hid_t plist, + H5MM_allocate_t *alloc, + void **alloc_info, + H5MM_free_t *free, + void **free_info + )
    Purpose: -
    Returns the number of filters in the pipeline. +
    Gets the memory manager for variable-length datatype allocation in + H5Dread and H5Dvlen_reclaim.
    Description: -
    H5Pget_nfilters returns the number of filters - defined in the filter pipeline associated with the property list - plist. -

    - In each pipeline, the filters are numbered from - 0 through N-1, where N is the value returned - by this function. During output to the file, the filters are - applied in increasing order; during input from the file, they - are applied in decreasing order. -

    - H5Pget_nfilters returns the number of filters - in the pipeline, including zero (0) if there - are none. -

    Note: -
    This function currently supports only the permanent filter - pipeline; plist_id must be a dataset creation - property list. +
    H5Pget_vlen_mem_manager is the companion function to + H5Pset_vlen_mem_manager, returning the parameters + set by that function.
    Parameters:
    hid_t plist -
    IN: Property list identifier. +
    IN: Identifier for the dataset transfer property list. +
    H5MM_allocate_t alloc +
    OUT: User's allocate routine, or   NULL + for system   malloc. +
    void *alloc_info +
    OUT: Extra parameter for user's allocation routine. +
    + Contents are ignored if preceding parameter is   + NULL. +
    H5MM_free_t free +
    OUT: User's free routine, or   NULL for + system free. +
    void *free_info +
    OUT: Extra parameter for user's free routine. +
    + Contents are ignored if preceding parameter is   + NULL.
    Returns: -
    Returns the number of filters in the pipeline if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value. +
    - +
    -
    Name: H5Pget_filter +
    Name: H5Pinsert +
    Signature: -
    H5Z_filter_t H5Pget_filter(hid_t plist, - int filter_number, - unsigned int *flags, - size_t *cd_nelmts, - unsigned int *cd_values, - size_t namelen, - char name[] - ) +
    herr_t H5Pinsert( + hid_t plid, + const char *name, + size_t size, + void *value, + H5P_prp_set_func_t set, + H5P_prp_get_func_t get, + H5P_prp_delete_func_t delete, + H5P_prp_copy_func_t copy, + H5P_prp_close_func_t close + ) +
    Purpose: -
    Returns information about a filter in a pipeline. +
    Registers a temporary property with a property list. +
    Description: -
    H5Pget_filter returns information about a - filter, specified by its filter number, in a filter pipeline, - specified by the property list with which it is associated. -

    - If plist is a dataset creation property list, - the pipeline is a permanent filter pipeline; - if plist is a dataset transfer property list, - the pipeline is a transient filter pipeline. -

    - On input, cd_nelmts indicates the number of entries - in the cd_values array, as allocated by the caller; - on return,cd_nelmts contains the number of values - defined by the filter. -

    - filter_number is a value between zero and - N-1, as described in - H5Pget_nfilters. - The function will return a negative value if the filter number - is out of range. -

    - If name is a pointer to an array of at least - namelen bytes, the filter name will be copied - into that array. The name will be null terminated if - namelen is large enough. The filter name returned - will be the name appearing in the file, the name registered - for the filter, or an empty string. -

    - The structure of the flags argument is discussed - in H5Pset_filter. -

    Note: -
    This function currently supports only the permanent filter - pipeline; plist must be a dataset creation property - list. -
    Parameters: -
    -
    hid_t plist -
    IN: Property list identifier. -
    int filter_number -
    IN: Sequence number within the filter pipeline of - the filter for which information is sought. -
    unsigned int *flags -
    OUT: Bit vector specifying certain general properties - of the filter. -
    size_t *cd_nelmts -
    IN/OUT: Number of elements in cd_values. -
    unsigned int *cd_values -
    OUT: Auxiliary data for the filter. -
    size_t namelen -
    IN: Anticipated number of characters in name. -
    char name[] -
    OUT: Name of the filter. -
    +
    H5Pinsert create a new property in a property list. + The property will exist only in this property list and copies made + from it. + +

    + The initial property value must be provided in + value and the property value will be set accordingly. + +

    + The name of the property must not already exist in this list, + or this routine will fail. + +

    + The set and get callback routines may + be set to NULL if they are not needed. + +

    + Zero-sized properties are allowed and do not store any data in the + property list. The default value of a zero-size property may be set + to NULL. They may be used to indicate the presence or absence of a + particular piece of information. +

    + + The set routine is called before a new value is copied + into the property. + The H5P_prp_set_func_t calback function is defined + as follows: +
      typedef herr_t (*H5P_prp_set_func_t)( + hid_t prop_id, + const char *name, + size_t size, + void *new_value); +
    + The parameters to the callback function are defined as follows: +
      + + + + + + + + + + + + +
      hid_t prop_idIN: The identifier of the property list being modified
      const char *nameIN: The name of the property being modified
      size_t sizeIN: The size of the property in bytes
      void **new_valueIN: Pointer to new value pointer for the property being + modified
    + The set routine may modify the value pointer to be set + and those changes will be used when setting the property's value. + If the set routine returns a negative value, the new + property value is not copied into the property and the set routine + returns an error value. + The set routine will be called for the initial value. +

    + Note: + The set callback function may be useful + to range check the value being set for the property + or may perform some tranformation or translation of the + value set. The get callback would then + reverse the transformation or translation. + A single get or set callback + could handle multiple properties by + performing different actions based on the + property name or other properties in the property list. + +

    + The get routine is called when a value is retrieved + from a property value. + The H5P_prp_get_func_t callback functioin is defined + as follows: +

      typedef herr_t (*H5P_prp_get_func_t)( + hid_t prop_id, + const char *name, + size_t size, + void *value); +
    + where the parameters to the callback function are: +
      + + + + + + + + + + + + +
      hid_t prop_idIN: The identifier of the property list being queried
      const char *nameIN: The name of the property being queried
      size_t sizeIN: The size of the property in bytes
      void *valueIN: The value of the property being returned
    + The get routine may modify the value to be returned from + the query and those changes will be preserved. + If the get routine returns a negative value, the query + routine returns an error value. +

    + + The delete routine is called when a property is being + deleted from a property list. + The H5P_prp_delete_func_t callback function is defined + as follows: +
      typedef herr_t (*H5P_prp_delete_func_t)( + hid_t prop_id, + const char *name, + size_t size, + void *value); +
    + where the parameters to the callback function are: +
      + + + + + + + + + + + + +
      hid_t prop_idIN: The identifier of the property list the property is + being deleted from
      const char * nameIN: The name of the property in the list
      size_t sizeIN: The size of the property in bytes
      void * valueIN: The value for the property being deleted
    + The delete routine may modify the value passed in, + but the value is not used by the library when the delete + routine returns. If the delete routine returns a + negative value, the property list delete routine returns an + error value but the property is still deleted. +

    + + The copy routine is called when a new property list + with this property is being created through a copy operation. + The H5P_prp_copy_func_t collback function is defined + as follows: +
      typedef herr_t (*H5P_prp_copy_func_t)( + const char *name, + size_t size, + void *value); +
    + where the parameters to the callback function are: +
      + + + + + + + + + +
      const char *nameIN: The name of the property being copied
      size_t sizeIN: The size of the property in bytes
      void * valueIN/OUT: The value for the property being copied
    + The copy routine may modify the value to be set and + those changes will be stored as the new value of the property. + If the copy routine returns a negative value, the + new property value is not copied into the property and the + copy routine returns an error value. + +

    The close routine is called when a property list + with this property is being closed. + The H5P_prp_close_func_t callback function is defined + as follows: +

      typedef herr_t (*H5P_prp_close_func_t)( + hid_t prop_id, + const char *name, + size_t size, + void *value); +
    + The parameters to the callback function are defined as follows: +
      + + + + + + + + + + + + +
      hid_t prop_idIN: The ID of the property list being closed
      const char *nameIN: The name of the property in the list
      size_t sizeIN: The size of the property in bytes
      void *valueIN: The value for the property being closed
    + The close routine may modify the value passed in, the value + is not used by the library when the close routine returns. + If the close routine returns a negative value, the + property list close routine returns an error value but the property list + is still closed. + +

    + Note: + There is no create callback routine for temporary property + list objects; the initial value is assumed to have any necessary setup + already performed on it. + +

    Parameters: +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      hid_t plidIN: Property list identifier to create temporary property + within
      const char *nameIN: Name of property to create
      size_t sizeIN: Size of property in bytes
      void *valueIN: Initial value for the property
      H5P_prp_set_func_t setIN: Callback routine called before a new value is copied into + the property's value
      H5P_prp_get_func_t getIN: Callback routine called when a property value is retrieved + from the property
      H5P_prp_delete_func_t deleteIN: Callback routine called when a property is deleted from + a property list
      H5P_prp_copy_func_t copyIN: Callback routine called when a property is copied from + an existing property list
      H5P_prp_close_func_t closeIN: Callback routine called when a property list is being closed + and the property value will be disposed of
    +
    Returns: -
    Returns the filter identifier if successful: -
    - - - - - -
    - H5Z_FILTER_DEFLATE - - Data compression filter, employing the gzip algorithm -
    - H5Z_FILTER_SHUFFLE - - Data shuffling filter -
    - H5Z_FILTER_FLETCHER32   - - Error detection filter, employing the Fletcher32 checksum algorithm -
    - H5Z_FILTER_SZIP - - Data compression filter, employing the SZIP algorithm -
    -
    - Otherwise returns a negative value. -
    Non-C API(s): -
    - +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    +
    - +
    -
    Name: H5Pget_filter_by_id +
    Name: H5Pisa_class +
    Signature: -
    herr_t H5Pget_filter_by_id( - hid_t plist_id, - H5Z_filter_t filter, - unsigned int *flags, - size_t *cd_nelmts, - unsigned int cd_values[], - size_t namelen, - char name[] - ) +
    htri_t H5Pisa_class( + hid_t plist, + hid_t pclass + ) +
    Purpose: -
    Returns information about the specified filter. +
    Determines whether a property list is a member of a class. +
    Description: -
    H5Pget_filter_by_id returns information about the - filter specified in filter, a filter identifier. -

    - plist_id must identify a dataset creation property list - and filter will be in a permanent filter pipeline. -

    - The filter and flags parameters are used - in the same manner as described in the discussion of - H5Pset_filter. -

    - Aside from the fact that they are used for output, the - parameters cd_nelmts and cd_values[] are - used in the same manner as described in the discussion - of H5Pset_filter. - On input, the cd_nelmts parameter indicates the - number of entries in the cd_values[] array - allocated by the calling program; on exit it contains the - number of values defined by the filter. -

    - On input, the name_len parameter indicates the - number of characters allocated for the filter name - by the calling program in the array name[]. - On exit it contains the length in characters of name of the filter. - On exit name[] contains the name of the filter - with one character of the name in each element of the array. -

    - If the filter specified in filter is not - set for the property list, an error will be returned - and H5Pget_filter_by_id will fail. -

    Parameters: -
    -
    hid_t plist_id -
    IN: Property list identifier. -
    H5Z_filter_t filter -
    IN: Filter identifier. -
    unsigned int flags -
    OUT: Bit vector specifying certain general properties - of the filter. -
    size_t cd_nelmts -
    IN/OUT: Number of elements in cd_values. -
    const unsigned int cd_values[] -
    OUT: Auxiliary data for the filter. -
    size_t namelen -
    IN/OUT: Length of filter name and - number of elements in name[]. -
    char *name[] -
    OUT: Name of filter. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - +
    H5Pisa_class checks to determine whether a property list + is a member of the specified class. + +
    Parameters: +
      + + + + + + +
      hid_t plistIN: Identifier of the property list
      hid_t pclassIN: Identifier of the property class
    + +
    Returns: +
    Success: TRUE (positive) if equal; FALSE (zero) if unequal +
    Failure: a negative value + +
    Non-C APIs: +
    + +
    + + + +
    +
    +
    Name: H5Piterate + +
    Purpose: +
    Iterates over properties in a property class or list. + +
    Signature: +
    int H5Piterate( + hid_t id, + int * idx, + H5P_iterate_t iter_func, + void * iter_data + ) + +
    Description: +

    H5Piterate iterates over the properties in the + property object specified in id, which may be either a + property list or a property class, performing a specified + operation on each property in turn. + +

    + For each property in the object, iter_func and + the additional information specified below are passed to the + H5P_iterate_t operator function. + + (NOTE: iter_func was changed to + H5P_iterate_t in the preceding sentence. + Is this correct?) + +

    + The iteration begins with the idx-th property in + the object; the next element to be processed by the operator + is returned in idx. + If idx is NULL, the iterator starts at the first + property; since no stopping point is returned in this case, + the iterator cannot be restarted if one of the calls to its + operator returns non-zero. +

    + + The prototype for the H5P_iterate_t operator is + as follows: +
      +
      typedef herr_t (*H5P_iterate_t)( + hid_t id, + const char *>name, + void *iter_data + ) +
    + The operation receives the property list or class identifier for + the object being iterated over, id, + the name of the current property within the object, name, + and the pointer to the operator data passed in to + H5Piterate, iter_data. +

    + + The valid return values from an operator are as follows: +
      + + + + + + + + + +
      ZeroCauses the iterator to continue, returning zero when all + properties have been processed
      PositiveCauses the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can + be restarted at the index of the next property
      NegativeCauses the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the + index of the next property
    + +

    + H5Piterate assumes that the properties in the object + identified by id remain unchanged through the iteration. + If the membership changes during the iteration, the function's behavior + is undefined. + +

    Parameters: +
      + + + + + + + + + + + + +
      hid_t idIN: Identifier of property object to iterate over
      int * idxIN/OUT: Index of the property to begin with
      H5P_iterate_t iter_funcIN: Function pointer to function to be called with each + property iterated over
      void * iter_dataIN/OUT: Pointer to iteration data from user
    + +
    Returns: +
    Success: the return value of the last call to + iter_func if it was non-zero; + zero if all properties have been processed +
    Failure: a negative value + + + +
    @@ -3965,571 +3954,460 @@ facilitate moving easily between them.
    - -
    -
    -
    Name: H5Pset_shuffle -
    Signature: -
    herr_t H5Pset_shuffle(hid_t plist_id) -
    Purpose: -
    Sets up use of the shuffle filter. -
    Description: -
    H5Pset_shuffle sets the shuffle filter, - H5Z_FILTER_SHUFFLE, - in the dataset creation property list plist_id.   -

    - The shuffle filter de-interlaces - a block of data by reordering the bytes. - All the bytes from one consistent byte position of - each data element are placed together in one block; - all bytes from a second consistent byte position of - each data element are placed together a second block; etc. - For example, given three data elements of a 4-byte datatype - stored as 012301230123, - shuffling will re-order data as 000111222333. - This can be a valuable step in an effective compression - algorithm because the bytes in each byte position are often - closely related to each other and putting them together - can increase the compression ratio. -

    - This filter is designed to be used in combination with - a compression filter. -

    Parameters: -
    -
    hid_t plist_id -
    IN: Dataset creation property list identifier. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - +
    -
    Name: H5Pset_fletcher32 -
    Signature: -
    herr_t H5Pset_fletcher32(hid_t plist) -
    Purpose: -
    Sets up use of the Fletcher32 checksum filter. -
    Description: -
    H5Pset_fletcher32 sets the Fletcher32 checksum filter - in the dataset creation property list plist.   -
    Note: -
    The initial error detection implementation supports - error detection for chunked datasets only. -
    Parameters: -
    -
    hid_t plist -
    IN: Dataset creation property list identifier. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    +
    Name: H5Pregister - - -
    -
    -
    Name: H5Pset_szip
    Signature: -
    herr_t H5Pset_szip(hid_t plist, - unsigned int options_mask, - unsigned int pixels_per_block) -
    Purpose: -
    Sets up use of the SZIP compression filter. -
    Description: -
    H5Pset_szip sets a filter for the dataset - to SZIP compression, H5Z_FILTER_SZIP, - a compression method designed for use with scientific data. -

    - SZIP options are passed in an options mask, options_mask, - as follows. -

    - - - - - - - - - - - - -
    -
    - Option -     		-
    - Description -
    - (Paired options are mutually exclusive.) -
    -
    - H5_SZIP_CHIP_OPTION_MASK   -     		-
    - Compresses exactly as in hardware. -
    - H5_SZIP_ALLOW_K13_OPTION_MASK   - - Allows k split = 13 compression mode. (Default) -
    -
    - H5_SZIP_EC_OPTION_MASK -     		-
    - Selects entropy coding method. (Default) -
    - H5_SZIP_NN_OPTION_MASK - - Selects nearest neighbor coding method. -
    -
    -     		-
    -
    -
    - Some typical usages are as follows: -
      -
    • One of the compression methods, - H5_SZIP_EC_OPTION_MASK or - H5_SZIP_NN_OPTION_MASK, is specified. -
    • The H5_SZIP_ALLOW_K13_OPTION_MASK is used. -
    -

    - Options are combined to create the options mask by means of - a logical OR operation. For example, the - option mask can be set as follows: -

         - options_mask = H5_SZIP_NN_OPTION_MASK | H5_SZIP_ALLOW_K13_OPTION_MASK; - -

    - SZIP compresses data block by block, with a user-tunable block size. - This block size is passed in the parameter - pixels_per_block and must be even, - with typical values being 8, 10, - 16, and 32. - The more pixel values vary, the smaller this number should be. - For optimal performance, the number of pixels per scan line - (i.e., the size of the fastest-changing dimension in the chunk) - should be an even multiple of the number of pixels per block. -

    -

    Notes: -
    SZIP works only with datasets with 1 through 24 bits/pixel, - 32 pits/pixel, or 64 bits/pixel. -

    - SZIP typically requires that the user application also supply - the number of pixels in the object to be compressed, - the number of bits per pixel, and the number of pixels per scan line. - These values need not be independently supplied in the HDF5 - environment as they are derived from the datatype and dataspace, - which are already known. -

    - Also see - SZIP Compression in HDF5 - for further discussion of SZIP compression in HDF5, - for important information regarding terms of use and - the SZIP copyright notice, - and for a list of SZIP-related references. - -

    Parameters: -
    -
    hid_t plist -
    IN: Dataset creation or dataset transfer property list - identifier. -
    unsigned int options_mask -
    IN: A bit-mask conveying the desired SZIP options. -
    unsigned int pixels_per_block -
    IN: The number of pixels or data elements in each data block. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - +
    herr_t H5Pregister( + hid_t class, + const char * name, + size_t size, + void * default, + H5P_prp_create_func_t create, + H5P_prp_set_func_t set, + H5P_prp_get_func_t get, + H5P_prp_delete_func_t delete, + H5P_prp_copy_func_t copy, + H5P_prp_close_func_t close + ) + +
    Purpose: +
    Registers a permanent property with a property list class. + +
    Description: +
    H5Pregister registers a new property with a + property list class. + The property will exist in all property list objects of + class created after this routine finishes. The name + of the property must not already exist, or this routine will fail. + The default property value must be provided and all new property + lists created with this property will have the property value set + to the default value. Any of the callback routines may be set to + NULL if they are not needed. - +
    Non-C APIs: +
    +
    - +
    -
    Name: H5Pset_edc_check -
    Signature: -
    herr_t H5Pset_edc_check(hid_t plist, - H5Z_EDC_t check) -
    Purpose: -
    Sets whether to enable error-detection when reading a dataset. -
    Description: -
    H5Pset_edc_check sets the dataset transfer property - list plist to enable or disable error detection - when reading data. -

    - Whether error detection is enabled or disabled is specified - in the check parameter. - Valid values are as follows: - - -
           - H5Z_ENABLE_EDC   (default) -
    - H5Z_DISABLE_EDC -
    -

    - The error detection algorithm used is the algorithm previously - specified in the corresponding dataset creation property list.   -

    - This function does not affect the use of error detection when - writing data.   -

    Note: -
    The initial error detection implementation, Fletcher32 checksum, - supports error detection for chunked datasets only. -
    Parameters: -
    -
    hid_t plist -
    IN: Dataset transfer property list identifier. -
    H5Z_EDC_t check -
    IN: Specifies whether error checking is enabled or disabled - for dataset read operations. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    +
    Name: H5Premove - - -
    -
    -
    Name: H5Pget_edc_check
    Signature: -
    H5Z_EDC_t H5Pget_edc_check(hid_t plist) -
    Purpose: -
    Determines whether error-detection is enabled for dataset reads. -
    Description: -
    H5Pget_edc_check queries the dataset transfer property - list plist to determine whether error detection - is enabled for data read operations. -
    Parameters: -
    -
    hid_t plist -
    IN: Dataset transfer property list identifier. -
    -
    Returns: -
    Returns H5P_ENABLE_EDC or H5P_DISABLE_EDC - if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    +
    herr_t H5Premove(plid, name) + hid_t plid; + const char *name + ) - - -
    -
    -
    Name: H5Pset_filter_callback -
    Signature: -
    herr_t H5Pset_filter_callback(hid_t plist, - H5Z_filter_func_t func, - void *op_data)
    Purpose: -
    Sets user-defined filter callback function. -
    Description: -
    H5Pset_filter_callback sets the user-defined - filter callback function func in the - dataset transfer property list plist. -

    - The parameter op_data is a pointer to user-defined - input data for the callback function and will be passed through - to the callback function. -

    - The callback function func defines the actions - an application is to take when a filter fails. - The function prototype is as follows: -

    - typedef H5Z_cb_return_t (H5Z_filter_func_t) - (H5Z_filter_t filter, - void *buf, - size_t buf_size, - void *op_data) - -

    - where filter indicates which filter has failed, - buf and buf_size are used to pass in - the failed data, - and op_data is the required input data for this - callback function. -

    - Valid callback function return values are - H5Z_CB_FAIL and H5Z_CB_CONT.   -

    Parameters: -
    -
    hid_t plist -
    IN: Dataset transfer property list identifier. -
    H5Z_filter_func_t func -
    IN: User-defined filter callback function. -
    void *op_data -
    IN: User-defined input data for the callback function. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. - -
    +
    Removes a property from a property list. - - -
    -
    -
    Name: H5Pset_meta_block_size -
    Signature: -
    herr_t H5Pset_meta_block_size( - hid_t fapl_id, - hsize_t size - ) -
    Purpose: -
    Sets the minimum metadata block size.
    Description: -
    H5Pset_meta_block_size sets the - minimum size, in bytes, of metadata block allocations when - H5FD_FEAT_AGGREGATE_METADATA is set by a VFL driver. -

    - Each raw metadata block is initially allocated to be of the - given size. Specific metadata objects (e.g., object headers, - local heaps, B-trees) are then sub-allocated from this block. -

    - The default setting is 2048 bytes, meaning that the library - will attempt to aggregate metadata in at least 2K blocks in the file. - Setting the value to 0 (zero) with this function - will turn off metadata aggregation, even if the VFL driver attempts - to use the metadata aggregation strategy. -

    - Metadata aggregation reduces the number of small data objects - in the file that would otherwise be required for metadata. - The aggregated block of metadata is usually written in a - single write action and always in a contiguous block, - potentially significantly improving library and application - performance. -

    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    hsize_t size -
    IN: Minimum size, in bytes, of metadata block allocations. -
    +
    H5Premove removes a property from a property list. + +

    + Both properties which were in existence when the property list + was created (i.e. properties registered with H5Pregister) + and properties added to the list after it was created (i.e. added + with H5Pinsert) may be removed from a property list. + Properties do not need to be removed from a property list before the + list itself is closed; they will be released automatically when + H5Pclose is called. + +

    + If a close callback exists for the removed property, + it will be called before the property is released. + +

    Parameters: +
      + + + + + + +
      hid_t plidIN: Identifier of the property list to modify
      const char *nameIN: Name of property to remove
    +
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    Non-C API(s): -
    - +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    +
    - +
    -
    Name: H5Pget_meta_block_size +
    Name: H5Pset +
    Signature: -
    herr_t H5Pget_meta_block_size( - hid_t fapl_id, - hsize_t *size - ) +
    herr_t H5Pset( + hid_t plid, + const char *name, + void *value) + ) +
    Purpose: -
    Returns the current metadata block size setting. +
    Sets a property list value. +
    Description: -
    H5Pget_meta_block_size returns the current - minimum size, in bytes, of new metadata block allocations. - This setting is retrieved from the file access property list - fapl_id. -

    - This value is set by - H5Pset_meta_block_size - and is retrieved from the file access property list - fapl_id. +

    H5Pset sets a new value for a property in a + property list. If there is a set callback + routine registered for this property, the value will be + passed to that routine and any changes to the value + will be used when setting the property value. + The information pointed to by the value pointer + (possibly modified by the set callback) is copied into + the property list value and may be changed by the application making + the H5Pset call without affecting the property value. + +

    + The property name must exist or this routine will fail. + +

    + If the set callback routine returns an error, the + property value will not be modified. + +

    + This routine may not be called for zero-sized properties + and will return an error in that case. +

    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    hsize_t *size -
    OUT: Minimum size, in bytes, of metadata block allocations. -
    -
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    Non-C API(s): -
    - +
      + + + + + + +
      hid_t plid; + IN: Property list identifier to modify
      const char *name; + IN: Name of property to modify
      void *value; + IN: Pointer to value to set the property to
    + +
    Returns: +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    +
    - +
    -
    Name: H5Pset_sieve_buf_size +
    Name: H5Pset_alignment
    Signature: -
    herr_t H5Pset_sieve_buf_size( - hid_t fapl_id, - hsize_t size +
    herr_t H5Pset_alignment(hid_t plist, + hsize_t threshold, + hsize_t alignment )
    Purpose: -
    Sets the maximum size of the data sieve buffer. +
    Sets alignment properties of a file access property list.
    Description: -
    H5Pset_sieve_buf_size sets size, - the maximum size in bytes of the data sieve buffer, which is - used by file drivers that are capable of using data sieving. -

    - The data sieve buffer is used when performing I/O on datasets - in the file. Using a buffer which is large enough to hold - several pieces of the dataset being read in for - hyperslab selections boosts performance by quite a bit. +

    H5Pset_alignment sets the alignment properties + of a file access property list + so that any file object greater than or equal in size to + threshold bytes will be aligned on an address + which is a multiple of alignment. The addresses + are relative to the end of the user block; the alignment is + calculated by subtracting the user block size from the + absolute file address and then adjusting the address to be a + multiple of alignment.

    - The default value is set to 64KB, indicating that file I/O for - raw data reads and writes will occur in at least 64KB blocks. - Setting the value to 0 with this API function will turn off the - data sieving, even if the VFL driver attempts to use that strategy. + Default values for threshold and + alignment are one, implying + no alignment. Generally the default values will result in + the best performance for single-process access to the file. + For MPI-IO and other parallel systems, choose an alignment + which is a multiple of the disk block size.

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    hsize_t size -
    IN: Maximum size, in bytes, of data sieve buffer. +
    hid_t plist +
    IN: Identifier for a file access property list. +
    hsize_t threshold +
    IN: Threshold value. + Must be non-negative. + Note that setting the threshold value to 0 (zero) has + the effect of a special case, forcing everything + to be aligned. +
    hsize_t alignment +
    IN: Alignment value. + Must be a positive value.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_sieve_buf_size +
    Name: H5Pset_alloc_time
    Signature: -
    herr_t H5Pget_sieve_buf_size( - hid_t fapl_id, - hsize_t *size - ) -
    -
    +
    herr_t H5Pset_alloc_time(hid_t plist_id, + H5D_alloc_time_t alloc_time + )
    Purpose: -
    Returns maximum data sieve buffer size. +
    Sets the timing for storage space allocation.
    Description: -
    H5Pget_sieve_buf_size retrieves, size, - the current maximum size of the data sieve buffer. +
    H5Pset_alloc_time sets up the timing for the allocation of + storage space for a dataset's raw data. + This property is set in the dataset creation property list + plist_id.

    - This value is set by - H5Pset_sieve_buf_size - and is retrieved from the file access property list - fapl_id. + Timing is specified in fill_time with one of the + following values: + +
         + H5D_ALLOC_TIME_DEFAULT   + + Allocate dataset storage space at the default time.
    + (Defaults differ by storage method.) +
    + H5D_ALLOC_TIME_EARLY + + Allocate all space when the dataset is created.
    + (Default for compact datasets.) +
    + H5D_ALLOC_TIME_INCR   + + Allocate space incrementally, as data is written to the dataset.
    + (Default for chunked storage datasets.) +
  • Chunked datasets: + Storage space allocation for each chunk is deferred until data + is written to the chunk. +
  • Contiguous datasets: + Incremental storage space allocation for contiguous data + is treated as late allocation. +
  • Compact datasets: + Incremental allocation is not allowed with compact datasets; + H5Pset_alloc_time will return an error. +
    • + H5D_ALLOC_TIME_LATE + + Allocate all space when data is first written to the dataset.
    + (Default for contiguous datasets.) +
    +

    Note: +
    H5Pset_alloc_time is designed to work in concert + with the dataset fill value and fill value write time properties, + set with the functions + H5Pset_fill_value and H5Pset_fill_time. +

    +

    + See H5Dcreate for + further cross-references.

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    hsize_t *size -
    IN: Maximum size, in bytes, of data sieve buffer. +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    H5D_alloc_time_t alloc_time +
    IN: When to allocate dataset storage space.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_gc_references +
    Name: H5Pset_btree_ratios
    Signature: -
    herr_t H5Pset_gc_reference(hid_t plist, - unsigned gc_ref +
    herr_t H5Pset_btree_ratios(hid_t plist, + double left, + double middle, + double right )
    Purpose: -
    Sets garbage collecting references flag. +
    Sets B-tree split ratios for a dataset transfer property list.
    Description: -
    H5Pset_gc_references sets the flag for - garbage collecting references for the file. +
    H5Pset_btree_ratios sets the B-tree split ratios + for a dataset transfer property list. The split ratios determine + what percent of children go in the first node when a node splits.

    - Dataset region references and other reference types use space - in an HDF5 file's global heap. If garbage collection is on - and the user passes in an uninitialized value in a reference structure, - the heap might get corrupted. When garbage collection is off, however, - and the user re-uses a reference, the previous heap block will be - orphaned and not returned to the free heap space. + The ratio left is used when the splitting node is + the left-most node at its level in the tree; + the ratio right is used when the splitting node is + the right-most node at its level; + and the ratio middle is used for all other cases.

    - When garbage collection is on, the user must initialize the - reference structures to 0 or risk heap corruption. + A node which is the only node at its level in the tree uses + the ratio right when it splits.

    - The default value for garbage collecting references is off. + All ratios are real numbers between 0 and 1, inclusive.

    Parameters:
    hid_t plist -
    IN: File access property list identifier. -
    unsigned gc_ref -
    IN: Flag setting reference garbage collection to - on (1) or off (0). +
    IN: The dataset transfer property list identifier. +
    double left +
    IN: The B-tree split ratio for left-most nodes. +
    double right +
    IN: The B-tree split ratio for right-most nodes and lone nodes. +
    double middle +
    IN: The B-tree split ratio for all other nodes.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_gc_references +
    Name: H5Pset_buffer
    Signature: -
    herr_t H5Pget_gc_references(hid_t plist, - unsigned *gc_ref - ) +
    herr_t H5Pset_buffer(hid_t plist, + hsize_t size, + void *tconv, + void *bkg + )
    Purpose: -
    Returns garbage collecting references setting. +
    Sets type conversion and background buffers.
    Description: -
    H5Pget_gc_references returns the current setting - for the garbage collection references property from - the specified file access property list. - The garbage collection references property is set - by H5Pset_gc_references. +
    Given a dataset transfer property list, H5Pset_buffer + sets the maximum size + for the type conversion buffer and background buffer and + optionally supplies pointers to application-allocated buffers. + If the buffer size is smaller than the entire amount of data + being transferred between the application and the file, and a type + conversion buffer or background buffer is required, then + strip mining will be used. +

    + Note that there are minimum size requirements for the buffer. + Strip mining can only break the data up along the first dimension, + so the buffer must be large enough to accommodate a complete slice + that encompasses all of the remaining dimensions. + For example, when strip mining a 100x200x300 hyperslab + of a simple data space, the buffer must be large enough to + hold 1x200x300 data elements. + When strip mining a 100x200x300x150 hyperslab of a simple data space, + the buffer must be large enough to hold 1x200x300x150 data elements. +

    + If tconv and/or bkg are null pointers, + then buffers will be allocated and freed during the data transfer. +

    + The default value for the maximum buffer is 1 Mb.

    Parameters:
    hid_t plist -
    IN: File access property list identifier. -
    unsigned gc_ref -
    OUT: Flag returning the state of reference garbage collection. - A returned value of 1 indicates that - garbage collection is on while - 0 indicates that garbage collection is off. +
    IN: Identifier for the dataset transfer property list. +
    hsize_t size +
    IN: Size, in bytes, of the type conversion and background buffers. +
    void tconv +
    IN: Pointer to application-allocated type conversion buffer. +
    void bkg +
    IN: Pointer to application-allocated background buffer.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - -
    -
    -
    Name: H5Pget_cache -
    Signature: -
    herr_t H5Pget_cache(hid_t plist_id, - int *mdc_nelmts, - int *rdcc_nelmts, - size_t *rdcc_nbytes, - double *rdcc_w0 - ) -
    Purpose: -
    Queries the meta data cache and raw data chunk cache parameters. -
    Description: -
    H5Pget_cache retrieves the maximum possible - number of elements in the meta - data cache and raw data chunk cache, the maximum possible number of - bytes in the raw data chunk cache, and the preemption policy value. -

    - Any (or all) arguments may be null pointers, in which case the - corresponding datum is not returned. -

    Parameters: -
    -
    hid_t plist_id -
    IN: Identifier of the file access property list. -
    int *mdc_nelmts -
    IN/OUT: Number of elements (objects) in the meta data cache. -
    int *rdcc_nelmts -
    IN/OUT: Number of elements (objects) in the raw data chunk cache. -
    size_t *rdcc_nbytes -
    IN/OUT: Total size of the raw data chunk cache, in bytes. -
    double *rdcc_w0 -
    IN/OUT: Preemption policy. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - -
    -
    -
    Name: H5Pset_hyper_cache -
    Signature: -
    herr_t H5Pset_hyper_cache(hid_t plist, - unsigned cache, - unsigned limit - ) -
    Purpose: -
    Indicates whether to cache hyperslab blocks during I/O. -
    Description: -
    [NOTE: - - This function is deprecated in HDF5 Release 1.6 - and will eventually be removed from the HDF5 distribution. - It is provided in this release only to enable backward compatibility - with HDF5 Releases 1.4.x - and is enabled only if the HDF5 library is configured - with the flag H5_WANT_H5_V1_4_COMPAT; - the function is not enabled in the binaries distributed by NCSA. - ] -

    - Given a dataset transfer property list, H5Pset_hyper_cache - indicates whether to cache hyperslab blocks during I/O, - a process which can significantly increase I/O speeds. -

    - When working with hyperslab selections, it is possible to - significantly speed up I/O operations by retrieving an - entire hyperslab from the file in one operation and - caching it in memory. - The cache parameter specifies whether to turn - caching on for hyperslab I/O operations. - If cache is set to 1, - caching is turned on; - if set to 0, caching is turned off. -

    - The parameter limit sets the maximum size of the - hyperslab block to cache. If a block is smaller than that limit, - it may still not be cached if no memory is available. - Setting limit to 0 (zero) indicates - no limitation on the size of block to attempt to cache. -

    - The default is to cache blocks with no limit on block size - for serial I/O and to not cache blocks for parallel I/O. -

    Parameters: -
    -
    hid_t plist -
    IN: Dataset transfer property list identifier. -
    unsigned cache -
    IN: A flag indicating whether caching is to be - set to on (1) or off (0). -
    unsigned limit -
    IN: Maximum size of the hyperslab block to cache. - 0 (zero) indicates no limit. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - +
    -
    Name: H5Pget_hyper_cache +
    Name: H5Pset_chunk
    Signature: -
    herr_t H5Pget_hyper_cache(hid_t plist, - unsigned *cache, - unsigned *limit - ) +
    herr_t H5Pset_chunk(hid_t plist, + int ndims, + const hsize_t * dim + )
    Purpose: -
    [NOTE: - - This function is deprecated in HDF5 Release 1.6 - and will eventually be removed from the HDF5 distribution. - It is provided in this release only to enable backward compatibility - with HDF5 Releases 1.4.x - and is enabled only if the HDF5 library is configured - with the flag H5_WANT_H5_V1_4_COMPAT; - the function is not enabled in the binaries distributed by NCSA. - ] -

    - Returns information regarding the caching of hyperslab blocks during I/O. +

    Sets the size of the chunks used to store a chunked layout dataset.
    Description: -
    Given a dataset transfer property list, H5Pget_hyper_cache - returns instructions regarding the caching of hyperslab blocks during I/O. - These parameters are set with the H5Pset_hyper_cache function. +
    H5Pset_chunk sets the size of the chunks used to + store a chunked layout dataset. This function is only valid + for dataset creation property lists. + The ndims parameter currently must be the same size + as the rank of the dataset. The values of the dim + array define the size of the chunks to store the dataset's raw data. + As a side-effect, the layout of the dataset is changed to + H5D_CHUNKED, if it is not already.
    Parameters:
    hid_t plist -
    IN: Dataset transfer property list identifier. -
    unsigned *cache -
    OUT: A flag indicating whether caching is - set to on (1) or off (0). -
    unsigned *limit -
    OUT: Maximum size of the hyperslab block to cache. - 0 (zero) indicates no limit. +
    IN: Identifier for property list to query. +
    int ndims +
    IN: The number of dimensions of each chunk. +
    const hsize_t * dim +
    IN: An array containing the size of each chunk.
    -
    Returns: +
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_hyper_vector_size +
    Name: H5Pset_deflate
    Signature: -
    herr_t H5Pset_hyper_vector_size(hid_t dxpl_id, - size_t vector_size +
    herr_t H5Pset_deflate(hid_t plist, + int level )
    Purpose: -
    Sets number of I/O vectors to be read/written in hyperslab I/O. +
    Sets compression method and compression level.
    Description: -
    H5Pset_hyper_vector_size sets the number of - I/O vectors to be accumulated in memory before being issued - to the lower levels of the HDF5 library for reading or writing the - actual data. -

    - The I/O vectors are hyperslab offset and length pairs - and are generated during hyperslab I/O. -

    - The number of I/O vectors is passed in vector_size - to be set in the dataset transfer property list dxpl_id. - vector_size must be greater than 1 (one). -

    - H5Pset_hyper_vector_size is an I/O optimization function; - increasing vector_size should provide better performance, - but the library will use more memory during hyperslab I/O. - The default value of vector_size is 1024. +

    H5Pset_deflate sets the compression method for a + dataset creation property list to H5D_COMPRESS_DEFLATE + and the compression level to level, which should + be a value from zero to nine, inclusive. + Lower compression levels are faster but result in less compression. + This is the same algorithm as used by the GNU gzip program.
    Parameters:
    -
    hid_t dxpl_id -
    IN: Dataset transfer property list identifier. -
    size_t vector_size -
    IN: Number of I/O vectors to accumulate in memory for I/O operations. - Must be greater than 1 (one). - Default value: 1024. +
    hid_t plist +
    IN: Identifier for the dataset creation property list. +
    int level +
    IN: Compression level.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_hyper_vector_size +
    Name: H5Pset_dxpl_mpio
    Signature: -
    herr_t H5Pget_hyper_vector_size(hid_t dxpl_id, - size_t *vector_size +
    herr_t H5Pset_dxpl_mpio( + hid_t dxpl_id, + H5FD_mpio_xfer_t xfer_mode )
    Purpose: -
    Retrieves number of I/O vectors to be read/written in hyperslab I/O. +
    Sets data transfer mode.
    Description: -
    H5Pset_hyper_vector_size retrieves the number of - I/O vectors to be accumulated in memory before being issued - to the lower levels of the HDF5 library for reading or writing the - actual data. +
    H5Pset_dxpl_mpio sets the data transfer property list + dxpl_id to use transfer mode xfer_mode. + The property list can then be used to control the I/O transfer mode + during data I/O operations.

    - The number of I/O vectors set in the dataset transfer property list - dxpl_id is returned in vector_size. - Unless the default value is in use, vector_size - was previously set with a call to - H5Pset_hyper_vector_size. + Valid transfer modes are as follows: +

    +
    +
    H5FD_MPIO_INDEPENDENT +
    Use independent I/O access (default). +
    H5FD_MPIO_COLLECTIVE +
    Use collective I/O access. +
    +
    Parameters:
    hid_t dxpl_id -
    IN: Dataset transfer property list identifier. -
    size_t *vector_size -
    OUT: Number of I/O vectors to accumulate in memory for I/O operations. +
    IN: Data transfer property list identifier. +
    H5FD_mpio_xfer_t xfer_mode +
    IN: Transfer mode.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. - - +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_btree_ratios +
    Name: H5Pset_dxpl_multi
    Signature: -
    herr_t H5Pset_btree_ratios(hid_t plist, - double left, - double middle, - double right +
    herr_t H5Pset_dxpl_multi( + hid_t dxpl_id, + const hid_t *memb_dxpl )
    Purpose: -
    Sets B-tree split ratios for a dataset transfer property list. +
    Sets the data transfer property list for the multi-file driver.
    Description: -
    H5Pset_btree_ratios sets the B-tree split ratios - for a dataset transfer property list. The split ratios determine - what percent of children go in the first node when a node splits. -

    - The ratio left is used when the splitting node is - the left-most node at its level in the tree; - the ratio right is used when the splitting node is - the right-most node at its level; - and the ratio middle is used for all other cases. -

    - A node which is the only node at its level in the tree uses - the ratio right when it splits. +

    H5Pset_dxpl_multi sets the data transfer property list + dxpl_id to use the multi-file driver for each + memory usage type memb_dxpl[].

    - All ratios are real numbers between 0 and 1, inclusive. + H5Pset_dxpl_multi can only be used after + the member map has been set with H5Pset_fapl_multi.

    Parameters:
    -
    hid_t plist -
    IN: The dataset transfer property list identifier. -
    double left -
    IN: The B-tree split ratio for left-most nodes. -
    double right -
    IN: The B-tree split ratio for right-most nodes and lone nodes. -
    double middle -
    IN: The B-tree split ratio for all other nodes. +
    hid_t dxpl_id, +
    IN: Data transfer property list identifier. +
    const hid_t *memb_dxpl +
    IN: Array of data access property lists.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    - +
    -
    Name: H5Pget_btree_ratios +
    Name: H5Pset_edc_check
    Signature: -
    herr_t H5Pget_btree_ratios(hid_t plist, - double *left, - double *middle, - double *right - ) +
    herr_t H5Pset_edc_check(hid_t plist, + H5Z_EDC_t check)
    Purpose: -
    Gets B-tree split ratios for a dataset transfer property list. +
    Sets whether to enable error-detection when reading a dataset.
    Description: -
    H5Pget_btree_ratios returns the B-tree split ratios - for a dataset transfer property list. -

    - The B-tree split ratios are returned through the non-NULL - arguments left, middle, and right, - as set by the H5Pset_btree_ratios function. +

    H5Pset_edc_check sets the dataset transfer property + list plist to enable or disable error detection + when reading data. +

    + Whether error detection is enabled or disabled is specified + in the check parameter. + Valid values are as follows: + + +
           + H5Z_ENABLE_EDC   (default) +
    + H5Z_DISABLE_EDC +
    +

    + The error detection algorithm used is the algorithm previously + specified in the corresponding dataset creation property list.   +

    + This function does not affect the use of error detection when + writing data.   +

    Note: +
    The initial error detection implementation, Fletcher32 checksum, + supports error detection for chunked datasets only.
    Parameters:
    hid_t plist -
    IN: The dataset transfer property list identifier. -
    double left -
    OUT: The B-tree split ratio for left-most nodes. -
    double right -
    OUT: The B-tree split ratio for right-most nodes and lone nodes. -
    double middle -
    OUT: The B-tree split ratio for all other nodes. +
    IN: Dataset transfer property list identifier. +
    H5Z_EDC_t check +
    IN: Specifies whether error checking is enabled or disabled + for dataset read operations.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    -
    - - - -
    -
    -
    Name: H5Pset_buffer -
    Signature: -
    herr_t H5Pset_buffer(hid_t plist, - hsize_t size, - void *tconv, - void *bkg - ) -
    Purpose: -
    Sets type conversion and background buffers. -
    Description: -
    Given a dataset transfer property list, H5Pset_buffer - sets the maximum size - for the type conversion buffer and background buffer and - optionally supplies pointers to application-allocated buffers. - If the buffer size is smaller than the entire amount of data - being transferred between the application and the file, and a type - conversion buffer or background buffer is required, then - strip mining will be used. -

    - Note that there are minimum size requirements for the buffer. - Strip mining can only break the data up along the first dimension, - so the buffer must be large enough to accommodate a complete slice - that encompasses all of the remaining dimensions. - For example, when strip mining a 100x200x300 hyperslab - of a simple data space, the buffer must be large enough to - hold 1x200x300 data elements. - When strip mining a 100x200x300x150 hyperslab of a simple data space, - the buffer must be large enough to hold 1x200x300x150 data elements. -

    - If tconv and/or bkg are null pointers, - then buffers will be allocated and freed during the data transfer. -

    - The default value for the maximum buffer is 1 Mb. + --> +

    + + + +
    +
    +
    Name: H5Pset_external +
    Signature: +
    herr_t H5Pset_external(hid_t plist, + const char *name, + off_t offset, + hsize_t size + ) +
    Purpose: +
    Adds an external file to the list of external files. +
    Description: +
    H5Pset_external adds an external file to the + list of external files. +

    + If a dataset is split across multiple files then the files + should be defined in order. The total size of the dataset is + the sum of the size arguments for all the external files. If + the total size is larger than the size of a dataset then the + dataset can be extended (provided the data space also allows + the extending). +

    + The size argument specifies number of bytes reserved + for data in the external file. + If size is set to H5F_UNLIMITED, the + external file can be of unlimited size and no more files can be added to + the external files list.

    Parameters:
    hid_t plist -
    IN: Identifier for the dataset transfer property list. +
    IN: Identifier of a dataset creation property list. +
    const char *name +
    IN: Name of an external file. +
    off_t offset +
    IN: Offset, in bytes, from the beginning of the file + to the location in the file where the data starts.
    hsize_t size -
    IN: Size, in bytes, of the type conversion and background buffers. -
    void tconv -
    IN: Pointer to application-allocated type conversion buffer. -
    void bkg -
    IN: Pointer to application-allocated background buffer. +
    IN: Number of bytes reserved in the file for the data.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_buffer +
    Name: H5Pset_family_offset
    Signature: -
    hsize_t H5Pget_buffer(hid_t plist, - void **tconv, - void **bkg - ) +
    herr_t H5Pset_family_offset ( + hid_t fapl_id, + hsize_t offset + )
    Purpose: -
    Reads buffer settings. +
    Sets offset property for low-level access to a file in a family of files.
    Description: -
    H5Pget_buffer reads values previously set - with H5Pset_buffer. +
    H5Pset_family_offset sets the offset property in the + file access property list fapl_id so that the user application + can retrieve a file handle for low-level access to a particluar member + of a family of files. The file handle is retrieved with a separate call + to H5Fget_vfd_handle + (or, in special circumstances, to H5FDget_vfd_handle; + see Virtual File Layer and List of VFL Functions + in HDF5 Technical Notes). +

    + The value of offset is an offset in bytes from the + beginning of the HDF5 file, identifying a user-determined location + within the HDF5 file. The file handle the user application is seeking + is for the specific member-file in the associated family of files + to which this offset is mapped. +

    + Use of this function is only appropriate for an HDF5 file written as a + family of files with the FAMILY file driver.

    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset transfer property list. -
    void **tconv -
    OUT: Address of the pointer to application-allocated - type conversion buffer. -
    void **bkg -
    OUT: Address of the pointer to application-allocated - background buffer. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    hsize_t offset +
    IN: Offset in bytes within the HDF5 file.
    Returns: -
    Returns buffer size, in bytes, if successful; - otherwise 0 on failure. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_small_data_block_size +
    Name: H5Pset_fapl_core
    Signature: -
    herr_t H5Pset_small_data_block_size(hid_t fapl_id, - hsize_t size - ) +
    herr_t H5Pset_fapl_core( + hid_t fapl_id, + size_t increment, + hbool_t backing_store + )
    Purpose: -
    Sets the size of a contiguous block reserved for small data. +
    Modifies the file access property list to use the + H5FD_CORE driver.
    Description: -
    H5Pset_small_data_block_size reserves blocks of - size bytes for the contiguous storage of the raw data - portion of small datasets. - The HDF5 library then writes the raw data from small datasets - to this reserved space, thus reducing unnecessary discontinuities - within blocks of meta data and improving IO performance. -

    - A small data block is actually allocated the first time a - qualifying small dataset is written to the file. - Space for the raw data portion of this small dataset is suballocated - within the small data block. - The raw data from each subsequent small dataset is also written to - the small data block until it is filled; additional small data blocks - are allocated as required. +

    H5Pset_fapl_core modifies the file access property list + to use the H5FD_CORE driver.

    - The HDF5 library employs an algorithm that determines whether - IO performance is likely to benefit from the use of this mechanism - with each dataset as storage space is allocated in the file. - A larger size will result in this mechanism being - employed with larger datasets. + The H5FD_CORE driver enables an application to work + with a file in memory, speeding reads and writes as no disk access + is made. File contents are stored only in memory until the file + is closed. The backing_store parameter determines + whether file contents are ever written to disk.

    - The small data block size is set as an allocation property in the - file access property list identified by fapl_id. + increment specifies the increment by which allocated + memory is to be increased each time more memory is required.

    - Setting size to zero (0) disables the - small data block mechanism. + If backing_store is set to 1 + (TRUE), the file contents are flushed to a file + with the same name as this core file when the file is closed + or access to the file is terminated in memory. +

    Note: +
    There is currently no means for reading a file from disk then + using the H5FD_CORE driver to manipulate the file.
    Parameters:
    hid_t fapl_id -
    IN: File access property list identifier . -
    hsize_t size -
    IN: Maximum size, in bytes, of the small data block. -
    - The default size is 2048. +
    IN: File access property list identifier. +
    size_t increment +
    IN: Size, in bytes, of memory increments. +
    hbool_t backing_store +
    IN: Boolean flag indicating whether to write the file + contents to disk when the file is closed.
    Returns: -
    Returns a non-negative value if successful; - otherwise a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_small_data_block_size +
    Name: H5Pset_fapl_family
    Signature: -
    herr_t H5Pget_small_data_block_size(hid_t fapl_id, - hsize_t *size - ) +
    herr_t H5Pset_fapl_family ( + hid_t fapl_id, + hsize_t memb_size, + hid_t memb_fapl_id + )
    Purpose: -
    Retrieves the current small data block size setting. +
    Sets the file access property list to use the family driver.
    Description: -
    H5Pget_small_data_block_size retrieves the - current setting for the size of the small data block. +
    H5Pset_fapl_family sets the file access property list + identifier, fapl_id, to use the family driver.

    - If the returned value is zero (0), the small data - block mechanism has been disabled for the file. + memb_size is the size in bytes of each file member + and is used only when creating a new file. +

    + memb_fapl_id is the identifier of the + file access property list to be used for each family member.

    Parameters:
    hid_t fapl_id -
    IN: File access property list identifier . -
    hsize_t *size -
    OUT: Maximum size, in bytes, of the small data block. +
    IN: File access property list identifier. +
    hsize_t memb_size +
    IN: Size in bytes of each file member. +
    hid_t memb_fapl_id +
    IN: Identifier of file access property list for each + family member.
    Returns:
    Returns a non-negative value if successful; - otherwise a negative value. + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_preserve +
    Name: H5Pset_fapl_gass
    Signature: -
    herr_t H5Pset_preserve(hid_t plist, - hbool_t status - ) +
    herr_t H5Pset_fapl_gass( + hid_t fapl_id, + GASS_Info info + )
    Purpose: -
    Sets the dataset transfer property list status to TRUE or FALSE. +
    Stores user-supplied GASS information.
    Description: -
    H5Pset_preserve sets the - dataset transfer property list status to TRUE or FALSE. +
    H5Pset_fapl_gass stores user-supplied GASS information, + the GASS_Info struct data as passed in info, + to the file access property list fapl_id. + fapl_id can then be used to create and/or open the file.

    - When reading or writing compound data types and the - destination is partially initialized and the read/write is - intended to initialize the other members, one must set this - property to TRUE. Otherwise the I/O pipeline treats the - destination datapoints as completely uninitialized. + The GASS_Info object, info, is used for + file open operations when using GASS in the Globus environment. +

    + Any modification to info after this function call + returns may have undetermined effect to the access property list. + Users must call H5Pset_fapl_gass again to setup + the property list. +

    Note: +
    H5Pset_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + GASS facility of the Globus environment. + For further information, see + http//www.globus.org/.
    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset transfer property list. -
    hbool_t status -
    IN: Status of for the dataset transfer property list - (TRUE/FALSE). +
    hid_t fapl_id, +
    IN: File access property list identifier. +
    GASS_Info info +
    IN: Pointer to the GASS information structure.
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns: +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    - +
    -
    Name: H5Pget_preserve +
    Name: H5Pset_fapl_log
    Signature: -
    int H5Pget_preserve(hid_t plist) +
    herr_t H5Pset_fapl_log( + hid_t fapl_id, + const char *logfile, + unsigned int flags, + size_t buf_size + )
    Purpose: -
    Checks status of the dataset transfer property list. +
    Sets up the use of the logging driver.
    Description: -
    H5Pget_preserve checks the status of the - dataset transfer property list. -
    Parameters: -
    -
    hid_t plist -
    IN: Identifier for the dataset transfer property list. -
    -
    Returns: -
    Returns TRUE or FALSE if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    +
    H5Pset_fapl_log modifies the + file access property list to use the logging driver + H5FD_LOG. +

    + logfile is the name of the file in which the + logging entries are to be recorded. +

    + The actions to be logged are specified in the parameter flags + using the pre-defined constants described in the following table. + Multiple flags can be set through the use of an logical OR contained + in parentheses. For example, logging read and write locations would + be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE). + +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + +
    +
    + Flag + +     		+
    + Description +
    +
    + H5FD_LOG_LOC_READ + +     		+
    + Track the location and length of every read, write, or seek operation. +
    + H5FD_LOG_LOC_WRITE   + +
    + H5FD_LOG_LOC_SEEK + +
    + H5FD_LOG_LOC_IO + + + Track all I/O locations and lengths. + The logical equivalent of the following: +
    +   + + (H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE | H5FD_LOG_LOC_SEEK) +
    +
    + H5FD_LOG_FILE_READ + +     		+
    + Track the number of times each byte is read or written. +
    + H5FD_LOG_FILE_WRITE   + +
    + H5FD_LOG_FILE_IO + + + Track the number of times each byte is read and written. + The logical equivalent of the following: +
    +   + + (H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE) +
    +
    + H5FD_LOG_FLAVOR + +     		+
    + Track the type, or flavor, of information stored at each byte. +
    +
    + H5FD_LOG_NUM_READ + +     		+
    + Track the total number of read, write, or seek operations that occur. +
    + H5FD_LOG_NUM_WRITE + +
    + H5FD_LOG_NUM_SEEK + +
    + H5FD_LOG_NUM_IO + + + Track the total number of all types of I/O operations. + The logical equivalent of the following: +
    +   + + (H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK) +
    +
    + H5FD_LOG_TIME_OPEN + +     		+
    + Track the time spent in open, read, write, seek, or close operations. + + + Not implemented in this release: open and read +
    + Partially implemented: write and seek +
    + Fully implemented: close     +     +
    + H5FD_LOG_TIME_READ + +
    + H5FD_LOG_TIME_WRITE + +
    + H5FD_LOG_TIME_SEEK + +
    + H5FD_LOG_TIME_CLOSE + +
    + H5FD_LOG_TIME_IO + + + Track the time spent in each of the above operations. + The logical equivalent of the following: +
    +   + + (H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE + | H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_CLOSE) +
    +
    + H5FD_LOG_ALLOC + +     		+
    + Track the allocation of space in the file. +
    +
    + Track everything. + The logical equivalent of the following: +
    +   + + (H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO | H5FD_LOG_FLAVOR + |H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO) +
    +
    +     		+
    +
    +
    -
    -
    -
    Name: H5Pset_compression -
    Signature: -
    herr_t H5Pset_compression(hid_t plist, - H5Z_method_t method, - unsigned int flags, - size_t cd_size, - const void *client_data - ) -
    Purpose: -
    Sets compression method. -
    Description: -
    H5Pset_compression sets the compression method - in a dataset creation property list. This is a catch-all - function for defining compression methods - and is intended to be called from a wrapper such as - H5Pset_deflate. The dataset creation property - list plist is adjusted to use the specified - compression method. The flags is an 8-bit vector - which is stored in the file as part of the compression message - and passed to the compress and uncompress functions. The - client_data is a byte array of length - cd_size which is copied to the file and passed to the - compress and uncompress methods. -

    - The FLAGS, CD_SIZE, and CLIENT_DATA are copied to the - property list and eventually to the file and passed to the - compression functions. -

    - See The Dataset Interface (H5D) - in the HDF5 User's Guide for further information - regarding data compression. +

    + The logging driver can track the number of times + each byte in the file is read from or written to + (using H5FD_LOG_FILE_READ and H5FD_LOG_FILE_WRITE) + and what kind of data is at that location + (e.g., meta data, raw data; using H5FD_LOG_FLAVOR). + This information is tracked in a buffer of size buf_size, + which must be at least the size in bytes of the file to be logged. +

    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset creation property list. -
    H5Z_method_t method -
    IN: Compression method, an integer from 16 to 225. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    char *logfile +
    IN: Name of the log file.
    unsigned int flags -
    IN: Compression flags. -
    size_t cd_size -
    IN: Size of the byte array client_data. -
    const void *client_data -
    IN: Client data byte array passed to the compression method. +
    IN: Flags specifying the types of logging activity. +
    size_t buf_size +
    IN: The size of the logging buffer.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns non-negative if successful. + Otherwise returns negative. + +
    ---> - - - +
    -
    Name: H5Pget_compression +
    Name: H5Pset_fapl_mpio
    Signature: -
    H5Z_method_t H5Pget_compression(hid_t plist, - unsigned int *flags, - size_t *cd_size, - void *client_data +
    herr_t H5Pset_fapl_mpio( + hid_t fapl_id, + MPI_Comm comm, + MPI_Info info )
    Purpose: -
    Gets compression method. +
    Stores MPI IO communicator information to the file access property list.
    Description: -
    H5Pget_compression gets the compression method - information from a dataset creation property list. - The client_data buffer is initially - cd_size bytes. On return, client_data - will be initialized with at most that many bytes, and - cd_size will contain the actual size of the - client data, which might be larger than its original value. +
    H5Pset_fapl_mpio stores the user-supplied + MPI IO parameters comm, for communicator, and + info, for information, in + the file access property list fapl_id. + That property list can then be used to create and/or open the file. +

    + H5Pset_fapl_mpio is available only in the + parallel HDF5 library and is not a collective function. +

    + comm is the MPI communicator to be used for + file open as defined in MPI_FILE_OPEN of MPI-2. + This function does not create a duplicated communicator. + Modifications to comm after this function call + returns may have an undetermined effect on the access property list. + Users should not modify the communicator while it is defined + in a property list. +

    + info is the MPI info object to be used for + file open as defined in MPI_FILE_OPEN of MPI-2. + This function does not create a duplicated info object. + Any modification to the info object after this function call + returns may have an undetermined effect on the access property list. + Users should not modify the info while it is defined + in a property list.

    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset creation property list. -
    unsigned int *flags -
    OUT: Compression flags. -
    size_t *cd_size -
    IN/OUT: Size of the client_data array. -
    void *client_data -
    OUT: Byte array for the client data. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    MPI_Comm comm +
    IN: MPI-2 communicator. +
    MPI_Info info +
    IN: MPI-2 info object.
    Returns: -
    Returns compression method if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    +
    ---> - - +
    -
    Name: H5Pset_deflate +
    Name: H5Pset_fapl_multi
    Signature: -
    herr_t H5Pset_deflate(hid_t plist, - int level +
    herr_t H5Pset_fapl_multi( + hid_t fapl_id, + const H5FD_mem_t *memb_map, + const hid_t *memb_fapl, + const char **memb_name, + const haddr_t *memb_addr, + hbool_t relax )
    Purpose: -
    Sets compression method and compression level. +
    Sets up use of the multi-file driver.
    Description: -
    H5Pset_deflate sets the compression method for a - dataset creation property list to H5D_COMPRESS_DEFLATE - and the compression level to level, which should - be a value from zero to nine, inclusive. - Lower compression levels are faster but result in less compression. - This is the same algorithm as used by the GNU gzip program. +
    H5Pset_fapl_multi sets the file access property list + fapl_id to use the multi-file driver. +

    + The multi-file driver enables different types of HDF5 data and + metadata to be written to separate files. These files are viewed + by the HDF5 library and the application as a single virtual HDF5 file + with a single HDF5 file address space. + The types of data that can be broken out into separate files include + raw data, the superblock, B-tree data, global heap data, + local heap data, and object headers. + At the programmer's discretion, two or more types of data can be + written to the same file while other types of data are written to + separate files. +

    + The array memb_map maps memory usage types to other + memory usage types and is the mechanism that allows the caller + to specify how many files are created. + The array contains H5FD_MEM_NTYPES entries, + which are either the value H5FD_MEM_DEFAULT + or a memory usage type. + The number of unique values determines the number of files + that are opened. +

    + The array memb_fapl contains a property list + for each memory usage type that will be associated with a file. +

    + The array memb_name should be a name generator + (a printf-style format with a %s which will be replaced with the + name passed to H5FDopen, usually from + H5Fcreate or H5Fopen). +

    + The array memb_addr specifies the offsets within the + virtual address space, from 0 (zero) to + HADDR_MAX, at which each type of data storage begins. +

    + If relax is set to TRUE (or 1), + then opening an existing file for read-only access will not fail + if some file members are missing. + This allows a file to be accessed in a limited sense if just the + meta data is available. +

    + Default values for each of the optional arguments are as follows: +

    +
    +
    memb_map +
    The default member map contains the value + H5FD_MEM_DEFAULT for each element. +
    memb_fapl +
    The default value is H5P_DEFAULT for each element. +
    memb_name +
    The default string is   %s-X.h5   + where   X   is one of the + following letters: + + s    for H5FD_MEM_SUPER +
    + b    for H5FD_MEM_BTREE +
    + r    for H5FD_MEM_DRAW +
    + g    for H5FD_MEM_GHEAP +
    + l    for H5FD_MEM_LHEAP +
    + o    for H5FD_MEM_OHDR +     +
    memb_addr +
    The default value is HADDR_UNDEF for each element. +
    +
    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset creation property list. -
    int level -
    IN: Compression level. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    const H5FD_mem_t *memb_map +
    IN: Maps memory usage types to other memory usage types. +
    const hid_t *memb_fapl +
    IN: Property list for each memory usage type. +
    const char **memb_name +
    IN: Name generator for names of member files. +
    const haddr_t *memb_addr +
    IN: The offsets within the virtual address space, + from 0 (zero) to HADDR_MAX, + at which each type of data storage begins. +
    hbool_t relax +
    IN: Allows read-only access to incomplete file sets + when TRUE.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    Example: +
    The following code sample sets up a multi-file access property list + that partitions data into meta and raw files, each being + one-half of the address: + 
    +                  H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
+                  hid_t memb_fapl[H5FD_MEM_NTYPES];
+                  const char *memb[H5FD_MEM_NTYPES];
+                  haddr_t memb_addr[H5FD_MEM_NTYPES];
+ 
+                  // The mapping...
+                  for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
+                     memb_map[mt] = H5FD_MEM_SUPER;
+                  }
+                  memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
+ 
+                  // Member information
+                  memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
+                  memb_name[H5FD_MEM_SUPER] = "%s.meta";
+                  memb_addr[H5FD_MEM_SUPER] = 0;
+ 
+                  memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
+                  memb_name[H5FD_MEM_DRAW] = "%s.raw";
+                  memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
+ 
+                  hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
+                  H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
+                                  memb_name, memb_addr, TRUE);
+
    Non-C API(s): -
    -->
    - - +
    -
    Name: H5Pget_deflate +
    Name: H5Pset_fapl_sec2
    Signature: -
    int H5Pget_deflate(hid_t plist +
    herr_t H5Pset_fapl_sec2( + hid_t fapl_id )
    Purpose: -
    Returns the deflate compression level from a dataset creation - property list. +
    Sets the sec2 driver.
    Description: -
    H5Pget_deflate returns the deflate compression level - from a dataset creation property list that uses that method. +
    H5Pset_fapl_sec2 modifies the file access property list + to use the H5FD_SEC2 driver.
    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset creation property list. +
    hid_t fapl_id +
    IN: File access property list identifier.
    Returns: -
    Returns compression level, a value between 0 and 9, if successful. +
    Returns a non-negative value if successful. Otherwise returns a negative value.
    Non-C API(s): -
    +
    ---> - - +
    -
    Name: H5Pset_vlen_mem_manager +
    Name: H5Pset_fapl_split
    Signature: -
    herr_t H5Pset_vlen_mem_manager(hid_t plist, - H5MM_allocate_t alloc, - void *alloc_info, - H5MM_free_t free, - void *free_info +
    herr_t H5Pset_fapl_split( + hid_t fapl_id, + const char *meta_ext, + hid_t meta_plist_id, + const char *raw_ext, + hid_t raw_plist_id )
    Purpose: -
    Sets the memory manager for variable-length datatype allocation in - H5Dread and H5Dvlen_reclaim. +
    Emulates the old split file driver.
    Description: -
    H5Pset_vlen_mem_manager sets the memory manager for - variable-length datatype allocation in H5Dread - and free in H5Dvlen_reclaim. -

    - The alloc and free parameters - identify the memory management routines to be used. - If the user has defined custom memory management routines, - alloc and/or free should be set to make - those routine calls (i.e., the name of the routine is used as - the value of the parameter); - if the user prefers to use the system's malloc - and/or free, the alloc and - free parameters, respectively, should be set to - NULL -

    - The prototypes for these user-defined functions would appear as follows: -
         - typedef void *(*H5MM_allocate_t)(size_t size, - void *alloc_info) ; - -
         - typedef void (*H5MM_free_t)(void *mem, - void *free_info) ; -
    - The alloc_info and free_info parameters - can be used to pass along any required information to - the user's memory management routines. +

    H5Pset_fapl_split is a compatibility function that + enables the multi-file driver to emulate the split driver from + HDF5 Releases 1.0 and 1.2. + The split file driver stored metadata and raw data in separate files + but provided no mechanism for separating types of metadata. +

    + fapl_id is a file access property list identifier. +

    + meta_ext is the filename extension for the metadata file. + The extension is appended to the name passed to H5FDopen, + usually from H5Fcreate or H5Fopen, + to form the name of the metadata file. + If the string %s is used in the extension, it works like the + name generator as in H5Pset_fapl_multi. +

    + meta_plist_id is the file access property list identifier + for the metadata file. +

    + raw_ext is the filename extension for the raw data file. + The extension is appended to the name passed to H5FDopen, + usually from H5Fcreate or H5Fopen, + to form the name of the rawdata file. + If the string %s is used in the extension, it works like the + name generator as in H5Pset_fapl_multi. +

    + raw_plist_id is the file access property list identifier + for the raw data file.

    - In summary, if the user has defined custom memory management - routines, the name(s) of the routines are passed in the - alloc and free parameters and the - custom routines' parameters are passed in the - alloc_info and free_info parameters. - If the user wishes to use the system malloc and - free functions, the alloc and/or - free parameters are set to NULL - and the alloc_info and free_info - parameters are ignored. + If a user wishes to check to see whether this driver is in use, + the user must call H5Pget_driver and compare the + returned value to the string H5FD_MULTI. + A positive match will confirm that the multi driver is in use; + HDF5 provides no mechanism to determine whether it was called + as the special case invoked by H5Pset_fapl_split.

    Parameters:
    -
    hid_t plist -
    IN: Identifier for the dataset transfer property list. -
    H5MM_allocate_t alloc -
    IN: User's allocate routine, or   NULL - for system   malloc. -
    void *alloc_info -
    IN: Extra parameter for user's allocation routine. -
    - Contents are ignored if preceding parameter is   - NULL. -
    H5MM_free_t free -
    IN: User's free routine, or   NULL - for system free. -
    void *free_info -
    IN: Extra parameter for user's free routine. -
    - Contents are ignored if preceding parameter is   - NULL. +
    +
    hid_t fapl_id, +
    IN: File access property list identifier. +
    const char *meta_ext, +
    IN: Metadata filename extension. +
    hid_t meta_plist_id, +
    IN: File access property list identifier for the metadata file. +
    const char *raw_ext, +
    IN: Raw data filename extension. +
    hid_t raw_plist_id +
    IN: File access property list identifier for the raw data file.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    - +
    -
    Name: H5Pget_vlen_mem_manager +
    Name: H5Pset_fapl_srb
    Signature: -
    herr_t H5Pget_vlen_mem_manager(hid_t plist, - H5MM_allocate_t *alloc, - void **alloc_info, - H5MM_free_t *free, - void **free_info +
    herr_t H5Pset_fapl_srb( + hid_t fapl_id, + SRB_Info info )
    Purpose: -
    Gets the memory manager for variable-length datatype allocation in - H5Dread and H5Dvlen_reclaim. +
    Saves SRB connection handler and sets SRB settings.
    Description: -
    H5Pget_vlen_mem_manager is the companion function to - H5Pset_vlen_mem_manager, returning the parameters - set by that function. -
    Parameters: -
    -
    hid_t plist -
    IN: Identifier for the dataset transfer property list. -
    H5MM_allocate_t alloc -
    OUT: User's allocate routine, or   NULL - for system   malloc. -
    void *alloc_info -
    OUT: Extra parameter for user's allocation routine. -
    - Contents are ignored if preceding parameter is   - NULL. -
    H5MM_free_t free -
    OUT: User's free routine, or   NULL for - system free. -
    void *free_info -
    OUT: Extra parameter for user's free routine. -
    - Contents are ignored if preceding parameter is   - NULL. +
    H5Pset_fapl_srb stores the SRB client-to-server + connection handler SRB_CONN after the connection + is established and other user-supplied SRB information. +

    + The user-supplied SRB information is contained in the + SRB_Info struct pointed to by info + and is stored in the file access property list fapl_id. + This information can then be used to create or open a file. +

    Note: +
    H5Pset_fapl_gass is an experimental function. + It is designed for use only when accessing files via the + Storage Resource Broker (SRB). For further information, see + http//www.npaci.edu/Research/DI/srb/. +
    Parameters: +
    +
    hid_t fapl_id +
    IN: File access property list identifier. +
    SRB_Info info +
    IN: Pointer to the SRB information structure.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    - - - - - - +
    -
    Name: H5Pset_fapl_family +
    Name: H5Pset_fapl_stdio
    Signature: -
    herr_t H5Pset_fapl_family ( - hid_t fapl_id, - hsize_t memb_size, - hid_t memb_fapl_id +
    herr_t H5Pset_fapl_stdio( + hid_t fapl_id )
    Purpose: -
    Sets the file access property list to use the family driver. +
    Sets the standard I/O driver.
    Description: -
    H5Pset_fapl_family sets the file access property list - identifier, fapl_id, to use the family driver. -

    - memb_size is the size in bytes of each file member - and is used only when creating a new file. -

    - memb_fapl_id is the identifier of the - file access property list to be used for each family member. +

    H5Pset_fapl_stdio modifies the file access property list + to use the standard I/O driver, H5FD_STDIO.
    Parameters:
    hid_t fapl_id
    IN: File access property list identifier. -
    hsize_t memb_size -
    IN: Size in bytes of each file member. -
    hid_t memb_fapl_id -
    IN: Identifier of file access property list for each - family member.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_fapl_family +
    Name: H5Pset_fapl_stream
    Signature: -
    herr_t H5Pget_fapl_family ( - hid_t fapl_id, - hsize_t *memb_size, - hid_t *memb_fapl_id +
    herr_t H5Pset_fapl_stream( + hid_t fapl_id, + H5FD_stream_fapl_t *fapl )
    Purpose: -
    Returns file access property list information. +
    Sets up the use of the streaming I/O driver.
    Description: -
    H5Pget_fapl_family returns file access property list - for use with the family driver. - This information is returned through the output parameters. +
    H5Pset_fapl_stream sets up the use of the + streaming I/O driver. +

    + fapl_id is the identifier for the + file access property list currently in use. +

    + fapl is the file access property list. +

    + The H5FD_stream_fapl_t struct contains the following + elements: +

    + + + + + + + + + + + + + + + + + + + +
    size_tincrement
    H5FD_STREAM_SOCKET_TYPEsocket
    hbool_tdo_socket_io
    unsigned intbacklog
    H5FD_stream_broadcast_tbroadcast_fn
    void *broadcast_arg
    +
      +
    • increment specifies how much memory to allocate + each time additional memory is required. +
    • socket is an external socket descriptor; + if a valid socket argument is provided, that socket will be used. +
    • do_socket_io is a boolean value specifying whether + to perform I/O on socket. +
    • backlog is the argument for the + listen call. +
    • broadcast_fn is the broadcast callback function. +
    • broadcast_arg is the user argument to + the broadcast callback function. +
    +     +

    + H5Pset_fapl_stream and H5Pget_fapl_stream + are not intended for use in a parallel environment.

    Parameters:
    hid_t fapl_id
    IN: File access property list identifier. -
    hsize_t *memb_size -
    OUT: Size in bytes of each file member. -
    hid_t *memb_fapl_id -
    OUT: Identifier of file access property list for each - family member. +
    H5FD_stream_fapl_t *fapl +
    IN: The streaming I/O file access property list.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value. +
    - +
    -
    Name: H5Pset_family_offset -
    Signature: -
    herr_t H5Pset_family_offset ( - hid_t fapl_id, - hsize_t offset - ) -
    Purpose: -
    Sets offset property for low-level access to a file in a family of files. -
    Description: -
    H5Pset_family_offset sets the offset property in the - file access property list fapl_id so that the user application - can retrieve a file handle for low-level access to a particluar member - of a family of files. The file handle is retrieved with a separate call - to H5Fget_vfd_handle - (or, in special circumstances, to H5FDget_vfd_handle; - see Virtual File Layer and List of VFL Functions - in HDF5 Technical Notes). -

    - The value of offset is an offset in bytes from the - beginning of the HDF5 file, identifying a user-determined location - within the HDF5 file. The file handle the user application is seeking - is for the specific member-file in the associated family of files - to which this offset is mapped. -

    - Use of this function is only appropriate for an HDF5 file written as a - family of files with the FAMILY file driver. -

    Parameters: +
    Name: H5Pset_fclose_degree +
    Signature: +
    herr_t H5Pset_fclose_degree(hid_t fapl_id, + H5F_close_degree_t fc_degree) +
    Purpose: +
    Sets the file close degree. +
    Description: +
    H5Pset_fclose_degree sets the file close degree property fc_degree + in the file access property list fapl_id.  +

    The value of fc_degree determines how aggressively H5Fclose + deals with objects within a file that remain open when H5Fclose + is called to close that file.  fc_degree can have any one of + four valid values: +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Degree nameH5Fclose behavior with no open object + in fileH5Fclose behavior with open object(s) + in file
    H5F_CLOSE_WEAKActual file is closed.Access to file identifier is terminated; actual file + close is delayed until all objects in file are closed
    H5F_CLOSE_SEMIActual file is closed.Function returns FAILURE
    H5F_CLOSE_STRONGActual file is closed.All open objects ramaining in the file are closed then + file is closed
    H5F_CLOSE_DEFAULTThe VFL driver chooses the behavior.  Currently, + all VFL drivers set this value to H5F_CLOSE_WEAK, except + for the MPI-I/O driver, which sets it to H5F_CLOSE_SEMI. +
    +
    +
    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    hsize_t offset -
    IN: Offset in bytes within the HDF5 file. +
    hid_t fapl_id +
    IN: File access property list identifier. +
    H5F_close_degree_t fc_degree +
    IN: Pointer to a location containing the file close degree property, + the value of fc_degree.
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns: +
    Returns a non-negative value if successful. Otherwise returns a negative + value.
    Non-C API(s): -
    -
    - +
    -
    Name: H5Pget_family_offset +
    Name: H5Pset_fill_time
    Signature: -
    herr_t H5Pget_family_offset ( - hid_t fapl_id, - hsize_t *offset - ) +
    herr_t H5Pset_fill_time(hid_t plist_id, + H5D_fill_time_t fill_time + )
    Purpose: -
    Retrieves a data offset from the file access property list. -
    Description: -
    H5Pget_family_offset retrieves the value of offset - from the file access property list fapl_id - so that the user application - can retrieve a file handle for low-level access to a particluar member - of a family of files. The file handle is retrieved with a separate call - to H5Fget_vfd_handle - (or, in special circumstances, to H5FDget_vfd_handle; - see Virtual File Layer and List of VFL Functions - in HDF5 Technical Notes). -

    - The data offset returned in offset is the offset - of the data in the HDF5 file that is stored on disk in the selected - member file in a family of files. +

    Sets the time when fill values are written to a dataset. +
    Description: +
    H5Pset_fill_time sets up the timing for writing fill values + to a dataset. + This property is set in the dataset creation property list plist_id. +

    + Timing is specified in fill_time with one of the following values: + +
         + H5D_FILL_TIME_IFSET   + + Write fill values to the dataset when storage space is allocated + only if there is a user-defined fill value, i.e., one set with + H5Pset_fill_value. +   (Default) +
      + H5D_FILL_TIME_ALLOC + + Write fill values to the dataset when storage space is allocated. +
      + H5D_FILL_TIME_NEVER + + Never write fill values to the dataset. +
    +

    Note: +
    H5Pset_fill_time is designed for coordination + with the dataset fill value and + dataset storage allocation time properties, set with the functions + H5Pset_fill_value and H5Pset_alloc_time.

    - Use of this function is only appropriate for an HDF5 file written as a - family of files with the FAMILY file driver. + See H5Dcreate for + further cross-references.

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    hsize_t *offset -
    IN: Offset in bytes within the HDF5 file. +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    H5D_fill_time_t fill_time +
    IN: When to write fill values to a dataset.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. -
    - +
    -
    Name: H5Pset_fapl_log +
    Name: H5Pset_fill_value
    Signature: -
    herr_t H5Pset_fapl_log( - hid_t fapl_id, - const char *logfile, - unsigned int flags, - size_t buf_size +
    herr_t H5Pset_fill_value(hid_t plist_id, + hid_t type_id, + const void *value )
    Purpose: -
    Sets up the use of the logging driver. +
    Sets the fill value for a dataset.
    Description: -
    H5Pset_fapl_log modifies the - file access property list to use the logging driver - H5FD_LOG. -

    - logfile is the name of the file in which the - logging entries are to be recorded. +

    H5Pset_fill_value sets the fill value for + a dataset in the dataset creation property list.

    - The actions to be logged are specified in the parameter flags - using the pre-defined constants described in the following table. - Multiple flags can be set through the use of an logical OR contained - in parentheses. For example, logging read and write locations would - be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE). - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + value is interpreted as being of datatype + type_id. This datatype may differ from that of + the dataset, but the HDF5 library must be able to convert + value to the dataset datatype when the dataset + is created. +

    + The default fill value is 0 (zero), which is + interpreted according to the actual dataset datatype. +

    + Setting value to NULL indicates + that the fill value is to be undefined. +

    Notes: +
    Applications sometimes write data only to portions of + an allocated dataset. It is often useful in such cases + to fill the unused space with a known + fill value. + This function allows the user application to set that fill value; + the functions + H5Dfill and + H5Pset_fill_time, + respectively, provide the ability + to apply the fill value on demand or + to set up its automatic application. +

    + A fill value should be defined so that it is appropriate for + the application. While the HDF5 default fill value is + 0 (zero), it is often appropriate to use another value. + It might be useful, for example, to use a value that is + known to be impossible for the application to legitimately generate. +

    + H5Pset_fill_value is designed to work in + concert with H5Pset_alloc_time and + H5Pset_fill_time. + H5Pset_alloc_time and H5Pset_fill_time + govern the timing of dataset storage allocation and fill value + write operations and can be important in tuning application + performance. +

    + See H5Dcreate for + further cross-references. +

    Parameters: +
    +
    hid_t plist_id +
    IN: Dataset creation property list identifier. +
    hid_t type_id, +
    IN: Datatype of value. +
    const void *value +
    IN: Pointer to buffer containing value to use as fill value. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + + + + + +
    +
    +
    Name: H5Pset_filter +
    Signature: +
    herr_t H5Pset_filter(hid_t plist, + H5Z_filter_t filter, + unsigned int flags, + size_t cd_nelmts, + const unsigned int cd_values[] + ) +
    Purpose: +
    Adds a filter to the filter pipeline. +
    Description: +
    H5Pset_filter adds the specified + filter and corresponding properties to the + end of an output filter pipeline. + If plist is a dataset creation property list, + the filter is added to the permanent filter pipeline; + if plist is a dataset transfer property list, + the filter is added to the transient filter pipeline. +

    + The array cd_values contains + cd_nelmts integers which are auxiliary data + for the filter. The integer values will be stored in the + dataset object header as part of the filter information. +

    + The flags argument is a bit vector with + the following fields specifying certain general properties + of the filter: +

    +
    -
    - Flag - -     		-
    - Description -
    -
    - H5FD_LOG_LOC_READ - -     		-
    - Track the location and length of every read, write, or seek operation. -
    - H5FD_LOG_LOC_WRITE   - -
    - H5FD_LOG_LOC_SEEK - -
    - H5FD_LOG_LOC_IO - - - Track all I/O locations and lengths. - The logical equivalent of the following: -
    -   - - (H5FD_LOG_LOC_READ | H5FD_LOG_LOC_WRITE | H5FD_LOG_LOC_SEEK) -
    -
    - H5FD_LOG_FILE_READ - -     		-
    - Track the number of times each byte is read or written. -
    - H5FD_LOG_FILE_WRITE   - -
    - H5FD_LOG_FILE_IO - - - Track the number of times each byte is read and written. - The logical equivalent of the following: -
    -   - - (H5FD_LOG_FILE_READ | H5FD_LOG_FILE_WRITE) -
    -
    - H5FD_LOG_FLAVOR - -     		-
    - Track the type, or flavor, of information stored at each byte. -
    -
    - H5FD_LOG_NUM_READ - -     		-
    - Track the total number of read, write, or seek operations that occur. -
    - H5FD_LOG_NUM_WRITE - -
    - H5FD_LOG_NUM_SEEK - -
    - H5FD_LOG_NUM_IO - - - Track the total number of all types of I/O operations. - The logical equivalent of the following: -
    -   - - (H5FD_LOG_NUM_READ | H5FD_LOG_NUM_WRITE | H5FD_LOG_NUM_SEEK) -
    -
    - H5FD_LOG_TIME_OPEN - -     		-
    - Track the time spent in open, read, write, seek, or close operations. - - - Not implemented in this release: open and read -
    - Partially implemented: write and seek -
    - Fully implemented: close     -     -
    - H5FD_LOG_TIME_READ - -
    - H5FD_LOG_TIME_WRITE - -
    - H5FD_LOG_TIME_SEEK - -
    - H5FD_LOG_TIME_CLOSE - -
    - H5FD_LOG_TIME_IO - - - Track the time spent in each of the above operations. - The logical equivalent of the following: -
    -   - - (H5FD_LOG_TIME_OPEN | H5FD_LOG_TIME_READ | H5FD_LOG_TIME_WRITE - | H5FD_LOG_TIME_SEEK | H5FD_LOG_TIME_CLOSE) -
    + + + + +
    H5Z_FLAG_OPTIONAL  If this bit is set then the filter is + optional. If the filter fails (see below) during an + H5Dwrite operation then the filter is + just excluded from the pipeline for the chunk for which + it failed; the filter will not participate in the + pipeline during an H5Dread of the chunk. + This is commonly used for compression filters: if the + filter result would be larger than the input, then + the compression filter returns failure and the + uncompressed data is stored in the file. If this bit is + clear and a filter fails, then H5Dwrite + or H5Dread also fails. +

    + This flag should not be set for the Fletcher32 checksum + filter as it will bypass the checksum filter without + reporting checksum errors to an application.

    +
    +

    + The filter parameter specifies the filter to be set. + Valid values are as follows: +

    + - - + Error detection filter, employing the Fletcher32 checksum algorithm + +
    -
    - H5FD_LOG_ALLOC - + H5Z_FILTER_DEFLATE     		-
    - Track the allocation of space in the file. + Data compression filter, employing the gzip algorithm
    -
    - H5FD_LOG_ALL - + H5Z_FILTER_SHUFFLE     		-
    - Track everything. - The logical equivalent of the following: + Data shuffling filter
    -   + H5Z_FILTER_FLETCHER32   - (H5FD_LOG_ALLOC | H5FD_LOG_TIME_IO | H5FD_LOG_NUM_IO | H5FD_LOG_FLAVOR - |H5FD_LOG_FILE_IO | H5FD_LOG_LOC_IO) -
    -
    + H5Z_FILTER_SZIP     		-
    + Data compression filter, employing the SZIP algorithm
    +
    +

    + Also see H5Pset_edc_check and + H5Pset_filter_callback. - -

    • - +
    Notes: +
    This function currently supports only the permanent filter + pipeline; plist must be a dataset creation + property list.

    - The logging driver can track the number of times - each byte in the file is read from or written to - (using H5FD_LOG_FILE_READ and H5FD_LOG_FILE_WRITE) - and what kind of data is at that location - (e.g., meta data, raw data; using H5FD_LOG_FLAVOR). - This information is tracked in a buffer of size buf_size, - which must be at least the size in bytes of the file to be logged. - + If multiple filters are set for a property list, they will be + applied to each chunk in the order in which they were set.

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    char *logfile -
    IN: Name of the log file. +
    hid_t plist +
    IN: Property list identifier. +
    H5Z_filter_t filter +
    IN: Filter to be added to the pipeline.
    unsigned int flags -
    IN: Flags specifying the types of logging activity. -
    size_t buf_size -
    IN: The size of the logging buffer. +
    IN: Bit vector specifying certain general properties + of the filter. +
    size_t cd_nelmts +
    IN: Number of elements in cd_values. +
    const unsigned int cd_values[] +
    IN: Auxiliary data for the filter.
    Returns: -
    Returns non-negative if successful. - Otherwise returns negative. - - +
    -
    Name: H5Pset_fapl_mpio +
    Name: H5Pset_filter_callback
    Signature: -
    herr_t H5Pset_fapl_mpio( - hid_t fapl_id, - MPI_Comm comm, - MPI_Info info - ) +
    herr_t H5Pset_filter_callback(hid_t plist, + H5Z_filter_func_t func, + void *op_data)
    Purpose: -
    Stores MPI IO communicator information to the file access property list. +
    Sets user-defined filter callback function.
    Description: -
    H5Pset_fapl_mpio stores the user-supplied - MPI IO parameters comm, for communicator, and - info, for information, in - the file access property list fapl_id. - That property list can then be used to create and/or open the file. -

    - H5Pset_fapl_mpio is available only in the - parallel HDF5 library and is not a collective function. -

    - comm is the MPI communicator to be used for - file open as defined in MPI_FILE_OPEN of MPI-2. - This function does not create a duplicated communicator. - Modifications to comm after this function call - returns may have an undetermined effect on the access property list. - Users should not modify the communicator while it is defined - in a property list. -

    - info is the MPI info object to be used for - file open as defined in MPI_FILE_OPEN of MPI-2. - This function does not create a duplicated info object. - Any modification to the info object after this function call - returns may have an undetermined effect on the access property list. - Users should not modify the info while it is defined - in a property list. -

    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    MPI_Comm comm -
    IN: MPI-2 communicator. -
    MPI_Info info -
    IN: MPI-2 info object. +
    H5Pset_filter_callback sets the user-defined + filter callback function func in the + dataset transfer property list plist. +

    + The parameter op_data is a pointer to user-defined + input data for the callback function and will be passed through + to the callback function. +

    + The callback function func defines the actions + an application is to take when a filter fails. + The function prototype is as follows: +

    + typedef H5Z_cb_return_t (H5Z_filter_func_t) + (H5Z_filter_t filter, + void *buf, + size_t buf_size, + void *op_data) + +

    + where filter indicates which filter has failed, + buf and buf_size are used to pass in + the failed data, + and op_data is the required input data for this + callback function. +

    + Valid callback function return values are + H5Z_CB_FAIL and H5Z_CB_CONT.   +

    Parameters: +
    +
    hid_t plist +
    IN: Dataset transfer property list identifier. +
    H5Z_filter_func_t func +
    IN: User-defined filter callback function. +
    void *op_data +
    IN: User-defined input data for the callback function.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    - +
    -
    Name: H5Pget_fapl_mpio +
    Name: H5Pset_fletcher32
    Signature: -
    herr_t H5Pget_fapl_mpio( - hid_t fapl_id, - MPI_Comm *comm, - MPI_Info *info - ) +
    herr_t H5Pset_fletcher32(hid_t plist)
    Purpose: -
    Returns MPI communicator information. +
    Sets up use of the Fletcher32 checksum filter.
    Description: -
    If the file access property list is set to the H5FD_MPIO - driver, H5Pget_fapl_mpio returns the MPI communicator and - information through the comm and info - pointers, if those values are non-null. -

    - Neither comm nor info is copied, - so they are valid only until the file access property list - is either modified or closed. +

    H5Pset_fletcher32 sets the Fletcher32 checksum filter + in the dataset creation property list plist.   +
    Note: +
    The initial error detection implementation supports + error detection for chunked datasets only.
    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    MPI_Comm *comm -
    OUT: MPI-2 communicator. -
    MPI_Info *info -
    OUT: MPI-2 info object. +
    hid_t plist +
    IN: Dataset creation property list identifier.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_fapl_mpio +
    Name: H5Pset_gc_references
    Signature: -
    herr_t H5Pset_fapl_mpiposix( - hid_t fapl_id, - MPI_Comm comm +
    herr_t H5Pset_gc_reference(hid_t plist, + unsigned gc_ref )
    Purpose: -
    Stores MPI IO communicator information to a file access property list. +
    Sets garbage collecting references flag.
    Description: -
    H5Pset_fapl_mpiposix stores the user-supplied - MPI IO parameter comm, for communicator, - in the file access property list fapl_id. - That property list can then be used to create and/or open the file. +
    H5Pset_gc_references sets the flag for + garbage collecting references for the file.

    - H5Pset_fapl_mpiposix is available only in the - parallel HDF5 library and is not a collective function. + Dataset region references and other reference types use space + in an HDF5 file's global heap. If garbage collection is on + and the user passes in an uninitialized value in a reference structure, + the heap might get corrupted. When garbage collection is off, however, + and the user re-uses a reference, the previous heap block will be + orphaned and not returned to the free heap space.

    - comm is the MPI communicator to be used for - file open as defined in MPI_FILE_OPEN of MPI-2. - This function does not create a duplicated communicator. - Modifications to comm after this function call - returns may have an undetermined effect on the access property list. - Users should not modify the communicator while it is defined - in a property list. -

    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    MPI_Comm comm -
    IN: MPI-2 communicator. -
    -
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. - -
    - - - -
    -
    -
    Name: H5Pget_fapl_mpiposix -
    Signature: -
    herr_t H5Pget_fapl_mpiposix( - hid_t fapl_id, - MPI_Comm *comm - ) -
    Purpose: -
    Returns MPI communicator information. -
    Description: -
    If the file access property list is set to the H5FD_MPIO - driver, H5Pget_fapl_mpiposix returns - the MPI communicator through the comm - pointer, if those values are non-null. + When garbage collection is on, the user must initialize the + reference structures to 0 or risk heap corruption.

    - comm is not copied, so it is valid only - until the file access property list is either modified or closed. + The default value for garbage collecting references is off.

    Parameters:
    -
    hid_t fapl_id +
    hid_t plist
    IN: File access property list identifier. -
    MPI_Comm *comm -
    OUT: MPI-2 communicator. +
    unsigned gc_ref +
    IN: Flag setting reference garbage collection to + on (1) or off (0).
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    - +
    -
    Name: H5Pset_dxpl_mpio +
    Name: H5Pset_hyper_cache
    Signature: -
    herr_t H5Pset_dxpl_mpio( - hid_t dxpl_id, - H5FD_mpio_xfer_t xfer_mode +
    herr_t H5Pset_hyper_cache(hid_t plist, + unsigned cache, + unsigned limit )
    Purpose: -
    Sets data transfer mode. +
    Indicates whether to cache hyperslab blocks during I/O.
    Description: -
    H5Pset_dxpl_mpio sets the data transfer property list - dxpl_id to use transfer mode xfer_mode. - The property list can then be used to control the I/O transfer mode - during data I/O operations. +
    [NOTE: + + This function is deprecated in HDF5 Release 1.6 + and will eventually be removed from the HDF5 distribution. + It is provided in this release only to enable backward compatibility + with HDF5 Releases 1.4.x + and is enabled only if the HDF5 library is configured + with the flag H5_WANT_H5_V1_4_COMPAT; + the function is not enabled in the binaries distributed by NCSA. + ]

    - Valid transfer modes are as follows: -

    -
    -
    H5FD_MPIO_INDEPENDENT -
    Use independent I/O access (default). -
    H5FD_MPIO_COLLECTIVE -
    Use collective I/O access. -
    -     + Given a dataset transfer property list, H5Pset_hyper_cache + indicates whether to cache hyperslab blocks during I/O, + a process which can significantly increase I/O speeds. +

    + When working with hyperslab selections, it is possible to + significantly speed up I/O operations by retrieving an + entire hyperslab from the file in one operation and + caching it in memory. + The cache parameter specifies whether to turn + caching on for hyperslab I/O operations. + If cache is set to 1, + caching is turned on; + if set to 0, caching is turned off. +

    + The parameter limit sets the maximum size of the + hyperslab block to cache. If a block is smaller than that limit, + it may still not be cached if no memory is available. + Setting limit to 0 (zero) indicates + no limitation on the size of block to attempt to cache. +

    + The default is to cache blocks with no limit on block size + for serial I/O and to not cache blocks for parallel I/O.

    Parameters:
    -
    hid_t dxpl_id -
    IN: Data transfer property list identifier. -
    H5FD_mpio_xfer_t xfer_mode -
    IN: Transfer mode. +
    hid_t plist +
    IN: Dataset transfer property list identifier. +
    unsigned cache +
    IN: A flag indicating whether caching is to be + set to on (1) or off (0). +
    unsigned limit +
    IN: Maximum size of the hyperslab block to cache. + 0 (zero) indicates no limit.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_dxpl_mpio +
    Name: H5Pset_hyper_vector_size
    Signature: -
    herr_t H5Pget_dxpl_mpio( - hid_t dxpl_id, - H5FD_mpio_xfer_t *xfer_mode +
    herr_t H5Pset_hyper_vector_size(hid_t dxpl_id, + size_t vector_size )
    Purpose: -
    Returns the data transfer mode. +
    Sets number of I/O vectors to be read/written in hyperslab I/O.
    Description: -
    H5Pget_dxpl_mpio queries the data transfer mode - currently set in the data transfer property list dxpl_id. +
    H5Pset_hyper_vector_size sets the number of + I/O vectors to be accumulated in memory before being issued + to the lower levels of the HDF5 library for reading or writing the + actual data.

    - Upon return, xfer_mode contains the data transfer mode, - if it is non-null. + The I/O vectors are hyperslab offset and length pairs + and are generated during hyperslab I/O.

    - H5Pget_dxpl_mpio is not a collective function. + The number of I/O vectors is passed in vector_size + to be set in the dataset transfer property list dxpl_id. + vector_size must be greater than 1 (one). +

    + H5Pset_hyper_vector_size is an I/O optimization function; + increasing vector_size should provide better performance, + but the library will use more memory during hyperslab I/O. + The default value of vector_size is 1024.

    Parameters:
    hid_t dxpl_id -
    IN: Data transfer property list identifier. -
    H5FD_mpio_xfer_t *xfer_mode -
    OUT: Data transfer mode. +
    IN: Dataset transfer property list identifier. +
    size_t vector_size +
    IN: Number of I/O vectors to accumulate in memory for I/O operations. + Must be greater than 1 (one). + Default value: 1024.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_fapl_multi +
    Name: H5Pset_istore_k
    Signature: -
    herr_t H5Pset_fapl_multi( - hid_t fapl_id, - const H5FD_mem_t *memb_map, - const hid_t *memb_fapl, - const char **memb_name, - const haddr_t *memb_addr, - hbool_t relax - ) +
    herr_t H5Pset_istore_k(hid_t plist, + int ik + )
    Purpose: -
    Sets up use of the multi-file driver. +
    Sets the size of the parameter used to control the + B-trees for indexing chunked datasets.
    Description: -
    H5Pset_fapl_multi sets the file access property list - fapl_id to use the multi-file driver. -

    - The multi-file driver enables different types of HDF5 data and - metadata to be written to separate files. These files are viewed - by the HDF5 library and the application as a single virtual HDF5 file - with a single HDF5 file address space. - The types of data that can be broken out into separate files include - raw data, the superblock, B-tree data, global heap data, - local heap data, and object headers. - At the programmer's discretion, two or more types of data can be - written to the same file while other types of data are written to - separate files. -

    - The array memb_map maps memory usage types to other - memory usage types and is the mechanism that allows the caller - to specify how many files are created. - The array contains H5FD_MEM_NTYPES entries, - which are either the value H5FD_MEM_DEFAULT - or a memory usage type. - The number of unique values determines the number of files - that are opened. -

    - The array memb_fapl contains a property list - for each memory usage type that will be associated with a file. -

    - The array memb_name should be a name generator - (a printf-style format with a %s which will be replaced with the - name passed to H5FDopen, usually from - H5Fcreate or H5Fopen). -

    - The array memb_addr specifies the offsets within the - virtual address space, from 0 (zero) to - HADDR_MAX, at which each type of data storage begins. -

    - If relax is set to TRUE (or 1), - then opening an existing file for read-only access will not fail - if some file members are missing. - This allows a file to be accessed in a limited sense if just the - meta data is available. -

    - Default values for each of the optional arguments are as follows: -

    -
    -
    memb_map -
    The default member map contains the value - H5FD_MEM_DEFAULT for each element. -
    memb_fapl -
    The default value is H5P_DEFAULT for each element. -
    memb_name -
    The default string is   %s-X.h5   - where   X   is one of the - following letters: - - s    for H5FD_MEM_SUPER -
    - b    for H5FD_MEM_BTREE -
    - r    for H5FD_MEM_DRAW -
    - g    for H5FD_MEM_GHEAP -
    - l    for H5FD_MEM_LHEAP -
    - o    for H5FD_MEM_OHDR -     -
    memb_addr -
    The default value is HADDR_UNDEF for each element. -
    -     +
    H5Pset_istore_k sets the size of the parameter + used to control the B-trees for indexing chunked datasets. + This function is only valid for file creation property lists. +

    + 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 fapl_id -
    IN: File access property list identifier. -
    const H5FD_mem_t *memb_map -
    IN: Maps memory usage types to other memory usage types. -
    const hid_t *memb_fapl -
    IN: Property list for each memory usage type. -
    const char **memb_name -
    IN: Name generator for names of member files. -
    const haddr_t *memb_addr -
    IN: The offsets within the virtual address space, - from 0 (zero) to HADDR_MAX, - at which each type of data storage begins. -
    hbool_t relax -
    IN: Allows read-only access to incomplete file sets - when TRUE. +
    hid_t plist +
    IN: Identifier of property list to query. +
    int ik +
    IN: 1/2 rank of chunked storage B-tree.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    Example: -
    The following code sample sets up a multi-file access property list - that partitions data into meta and raw files, each being - one-half of the address: - 
    -                  H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES];
-                  hid_t memb_fapl[H5FD_MEM_NTYPES];
-                  const char *memb[H5FD_MEM_NTYPES];
-                  haddr_t memb_addr[H5FD_MEM_NTYPES];
- 
-                  // The mapping...
-                  for (mt=0; mt<H5FD_MEM_NTYPES; mt++) {
-                     memb_map[mt] = H5FD_MEM_SUPER;
-                  }
-                  memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW;
- 
-                  // Member information
-                  memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT;
-                  memb_name[H5FD_MEM_SUPER] = "%s.meta";
-                  memb_addr[H5FD_MEM_SUPER] = 0;
- 
-                  memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT;
-                  memb_name[H5FD_MEM_DRAW] = "%s.raw";
-                  memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2;
- 
-                  hid_t fapl = H5Pcreate(H5P_FILE_ACCESS);
-                  H5Pset_fapl_multi(fapl, memb_map, memb_fapl,
-                                  memb_name, memb_addr, TRUE);
-
    +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pget_fapl_multi +
    Name: H5Pset_layout
    Signature: -
    herr_t H5Pget_fapl_multi( - hid_t fapl_id, - const H5FD_mem_t *memb_map, - const hid_t *memb_fapl, - const char **memb_name, - const haddr_t *memb_addr, - hbool_t *relax - ) +
    herr_t H5Pset_layout(hid_t plist, + H5D_layout_t layout + )
    Purpose: -
    Returns information about the multi-file access property list. +
    Sets the type of storage used to store the raw data for a dataset.
    Description: -
    H5Pget_fapl_multi returns information about the - multi-file access property list. +
    H5Pset_layout sets the type of storage used to store the + raw data for a dataset. + This function is only valid for dataset creation property lists. +

    + Valid values for layout are: +

      +
      H5D_COMPACT +
      Store raw data in the dataset object header in file. + This should only be used for very small amounts of raw + data. + The current limit is approximately 64K (HDF5 Release 1.6). +
      H5D_CONTIGUOUS +
      Store raw data separately from the object header in one + large chunk in the file. +
      H5D_CHUNKED +
      Store raw data separately from the object header as + chunks of data in separate locations in the file. +
    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    const H5FD_mem_t *memb_map -
    OUT: Maps memory usage types to other memory usage types. -
    const hid_t *memb_fapl -
    OUT: Property list for each memory usage type. -
    const char **memb_name -
    OUT: Name generator for names of member files. -
    const haddr_t *memb_addr -
    OUT: -
    hbool_t *relax -
    OUT: Allows read-only access to incomplete file sets - when TRUE. +
    hid_t plist +
    IN: Identifier of property list to query. +
    H5D_layout_t layout +
    IN: Type of storage layout for raw data.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Pset_dxpl_multi +
    Name: H5Punregister +
    Signature: -
    herr_t H5Pset_dxpl_multi( - hid_t dxpl_id, - const hid_t *memb_dxpl - ) +
    herr_t H5Punregister( + H5P_class_t class, + const char *name + ) +
    Purpose: -
    Sets the data transfer property list for the multi-file driver. +
    Removes a property from a property list class. +
    Description: -
    H5Pset_dxpl_multi sets the data transfer property list - dxpl_id to use the multi-file driver for each - memory usage type memb_dxpl[]. -

    - H5Pset_dxpl_multi can only be used after - the member map has been set with H5Pset_fapl_multi. -

    Parameters: -
    -
    hid_t dxpl_id, -
    IN: Data transfer property list identifier. -
    const hid_t *memb_dxpl -
    IN: Array of data access property lists. -
    +
    H5Punregister removes a property from a + property list class. + +

    + Future property lists created of that class will not contain + this property; + existing property lists containing this property are not affected. + +

    Parameters: +
      + + + + + + +
      H5P_class_t classIN: Property list class from which to remove + permanent property
      const char *nameIN: Name of property to remove
    +
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. - - +
    Success: a non-negative value +
    Failure: a negative value + +
    Non-C APIs: +
    +
    + + + + + + - +
    -
    Name: H5Pget_dxpl_multi +
    Name: H5Pset_userblock
    Signature: -
    herr_t H5Pget_dxpl_multi( - hid_t dxpl_id, - const hid_t *memb_dxpl - ) -
    -
    +
    herr_t H5Pset_userblock(hid_t plist, + hsize_t size + )
    Purpose: -
    Returns multi-file data transfer property list information. +
    Sets user block size.
    Description: -
    H5Pget_dxpl_multi returns the data transfer property list - information for the multi-file driver. +
    H5Pset_userblock sets the user block size of a + file creation property list. + The default user block size is 0; it may be set to any + power of 2 equal to 512 or greater (512, 1024, 2048, etc.).
    Parameters:
    -
    hid_t dxpl_id, -
    IN: Data transfer property list identifier. -
    const hid_t *memb_dxpl -
    OUT: Array of data access property lists. +
    hid_t plist +
    IN: Identifier of property list to modify. +
    hsize_t size +
    IN: Size of the user-block in bytes.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    + + - +
    -
    Name: H5Pset_fapl_split +
    Name: H5Pset_sizes
    Signature: -
    herr_t H5Pset_fapl_split( - hid_t fapl_id, - const char *meta_ext, - hid_t meta_plist_id, - const char *raw_ext, - hid_t raw_plist_id - ) +
    herr_t H5Pset_sizes(hid_t plist, + size_t sizeof_addr, + size_t sizeof_size + )
    Purpose: -
    Emulates the old split file driver. +
    Sets the byte size of the offsets and lengths used to address objects + in an HDF5 file.
    Description: -
    H5Pset_fapl_split is a compatibility function that - enables the multi-file driver to emulate the split driver from - HDF5 Releases 1.0 and 1.2. - The split file driver stored metadata and raw data in separate files - but provided no mechanism for separating types of metadata. -

    - fapl_id is a file access property list identifier. -

    - meta_ext is the filename extension for the metadata file. - The extension is appended to the name passed to H5FDopen, - usually from H5Fcreate or H5Fopen, - to form the name of the metadata file. - If the string %s is used in the extension, it works like the - name generator as in H5Pset_fapl_multi. -

    - meta_plist_id is the file access property list identifier - for the metadata file. -

    - raw_ext is the filename extension for the raw data file. - The extension is appended to the name passed to H5FDopen, - usually from H5Fcreate or H5Fopen, - to form the name of the rawdata file. - If the string %s is used in the extension, it works like the - name generator as in H5Pset_fapl_multi. -

    - raw_plist_id is the file access property list identifier - for the raw data file. -

    - If a user wishes to check to see whether this driver is in use, - the user must call H5Pget_driver and compare the - returned value to the string H5FD_MULTI. - A positive match will confirm that the multi driver is in use; - HDF5 provides no mechanism to determine whether it was called - as the special case invoked by H5Pset_fapl_split. +

    H5Pset_sizes sets the byte size of the offsets and lengths used to + address objects in an HDF5 file. This function is only valid for + file creation property lists. Passing in a value of 0 for one of the + sizeof parameters retains the current value. The default value + for both values is same as sizeof(hsize_t) in the library + (normally 8 bytes). Valid values currently are 2, 4, + 8 and 16.
    Parameters:
    -
    -
    hid_t fapl_id, -
    IN: File access property list identifier. -
    const char *meta_ext, -
    IN: Metadata filename extension. -
    hid_t meta_plist_id, -
    IN: File access property list identifier for the metadata file. -
    const char *raw_ext, -
    IN: Raw data filename extension. -
    hid_t raw_plist_id -
    IN: File access property list identifier for the raw data file. +
    hid_t plist +
    IN: Identifier of property list to modify. +
    size_t sizeof_addr +
    IN: Size of an object offset in bytes. +
    size_t sizeof_size +
    IN: Size of an object length in bytes.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    Example: -
    -
    -/* Example 1: Both metadata and rawdata files are in the same  */
-/*    directory.   Use Station1-m.h5 and Station1-r.h5 as      */
-/*    the metadata and rawdata files.                          */
-hid_t fapl, fid;
-fapl = H5Pcreate(H5P_FILE_ACCESS);
-H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT);
-fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-
-/* Example 2: metadata and rawdata files are in different      */
-/*    directories.  Use PointA-m.h5 and /pfs/PointA-r.h5 as    */
-/*    the metadata and rawdata files.                          */
-hid_t fapl, fid;
-fapl = H5Pcreate(H5P_FILE_ACCESS);
-H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT);
-fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
-
    +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    + + - +
    -
    Name: H5Pset_multi_type +
    Name: H5Pset_sym_k
    Signature: -
    herr_t H5Pset_multi_type ( - hid_t fapl_id, - H5FD_mem_t type - ) +
    herr_t H5Pset_sym_k(hid_t plist, + int ik, + int lk + )
    Purpose: -
    Sets data type property for MULTI driver. +
    Sets the size of parameters used to control the symbol table nodes.
    Description: -
    H5Pset_multi_type sets the data type property in the - file access or data transfer property list fapl_id. - This enables a user application to specifiy the type of data the - appication wishes to access so that the application - can retrieve a file handle for low-level access to the particular member - of a set of MULTI files in which that type of data is stored. - The file handle is retrieved with a separate call - to H5Fget_vfd_handle - (or, in special circumstances, to H5FDget_vfd_handle; - see Virtual File Layer and List of VFL Functions - in HDF5 Technical Notes). -

    - The type of data specified in type may be one of the following: - - - - - - - - -
         - H5FD_MEM_DEFAULT   - - Need description.... -
      - H5FD_MEM_SUPER - - Super block ... need description.... -
      - H5FD_MEM_BTREE - - Btree ... need description.... -
      - H5FD_MEM_DRAW - - Need description.... -
      - H5FD_MEM_GHEAP - - Global heap ... need description.... -
      - H5FD_MEM_LHEAP - - Local Heap ... need description.... -
      - H5FD_MEM_OHDR - - Need description.... -
    -

    - Use of this function is only appropriate for an HDF5 file written - as a set of files with the MULTI file driver. +

    H5Pset_sym_k sets the size of parameters used to + control the symbol table nodes. This function is only valid + for file creation property lists. Passing in a value of 0 for + one of the parameters retains the current value. +

    + ik is one half the rank of a tree that stores a symbol + table for a group. Internal nodes of the symbol table are on + average 75% full. That is, the average rank of the tree is + 1.5 times the value of ik. +

    + lk is one half of the number of symbols that can + be stored in a symbol table node. A symbol table node is the + leaf of a symbol table tree which is used to store a group. + When symbols are inserted randomly into a group, the group's + symbol table nodes are 75% full on average. That is, they + contain 1.5 times the number of symbols specified by + lk.

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list or data transfer property list identifier. -
    H5FD_mem_t type -
    OUT: Type of data. +
    hid_t plist +
    IN: Identifier for property list to query. +
    int ik +
    IN: Symbol table tree rank. +
    int lk +
    IN: Symbol table node size.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. -
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - +
    -
    Name: H5Pget_multi_type +
    Name: H5Pset_shuffle
    Signature: -
    herr_t H5Pset_multi_type ( - hid_t fapl_id, - H5FD_mem_t *type - ) +
    herr_t H5Pset_shuffle(hid_t plist_id)
    Purpose: -
    Retrieves data type property for MULTI driver. +
    Sets up use of the shuffle filter.
    Description: -
    H5Pget_multi_type retrieves the data type setting from the - file access or data transfer property list fapl_id. - This enables a user application to specifiy the type of data the - application wishes to access so that the application - can retrieve a file handle for low-level access to the particular member - of a set of MULTI files in which that type of data is stored. - The file handle is retrieved with a separate call - to H5Fget_vfd_handle - (or, in special circumstances, to H5FDget_vfd_handle; - see Virtual File Layer and List of VFL Functions - in HDF5 Technical Notes). +
    H5Pset_shuffle sets the shuffle filter, + H5Z_FILTER_SHUFFLE, + in the dataset creation property list plist_id.  

    - The type of data returned in type will be one of those - listed in the discussion of the type parameter in the the - description of the function - H5Pset_multi_type. + The shuffle filter de-interlaces + a block of data by reordering the bytes. + All the bytes from one consistent byte position of + each data element are placed together in one block; + all bytes from a second consistent byte position of + each data element are placed together a second block; etc. + For example, given three data elements of a 4-byte datatype + stored as 012301230123, + shuffling will re-order data as 000111222333. + This can be a valuable step in an effective compression + algorithm because the bytes in each byte position are often + closely related to each other and putting them together + can increase the compression ratio.

    - Use of this function is only appropriate for an HDF5 file written - as a set of files with the MULTI file driver. + This filter is designed to be used in combination with + a compression filter.

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list or data transfer property list identifier. -
    H5FD_mem_t *type -
    OUT: Type of data. +
    hid_t plist_id +
    IN: Dataset creation property list identifier.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. -
    + + - +
    -
    Name: H5Pset_fapl_sec2 +
    Name: H5Pset_szip
    Signature: -
    herr_t H5Pset_fapl_sec2( - hid_t fapl_id - ) +
    herr_t H5Pset_szip(hid_t plist, + unsigned int options_mask, + unsigned int pixels_per_block)
    Purpose: -
    Sets the sec2 driver. +
    Sets up use of the SZIP compression filter.
    Description: -
    H5Pset_fapl_sec2 modifies the file access property list - to use the H5FD_SEC2 driver. +
    H5Pset_szip sets a filter for the dataset + to SZIP compression, H5Z_FILTER_SZIP, + a compression method designed for use with scientific data. +

    + SZIP options are passed in an options mask, options_mask, + as follows. +

    + + + + + + + + + + + + +
    +
    + Option +     		+
    + Description +
    + (Paired options are mutually exclusive.) +
    +
    + H5_SZIP_CHIP_OPTION_MASK   +     		+
    + Compresses exactly as in hardware. +
    + H5_SZIP_ALLOW_K13_OPTION_MASK   + + Allows k split = 13 compression mode. (Default) +
    +
    + H5_SZIP_EC_OPTION_MASK +     		+
    + Selects entropy coding method. (Default) +
    + H5_SZIP_NN_OPTION_MASK + + Selects nearest neighbor coding method. +
    +
    +     		+
    +
    +
    + Some typical usages are as follows: +
      +
    • One of the compression methods, + H5_SZIP_EC_OPTION_MASK or + H5_SZIP_NN_OPTION_MASK, is specified. +
    • The H5_SZIP_ALLOW_K13_OPTION_MASK is used. +
    +

    + Options are combined to create the options mask by means of + a logical OR operation. For example, the + option mask can be set as follows: +

         + options_mask = H5_SZIP_NN_OPTION_MASK | H5_SZIP_ALLOW_K13_OPTION_MASK; + +

    + SZIP compresses data block by block, with a user-tunable block size. + This block size is passed in the parameter + pixels_per_block and must be even, + with typical values being 8, 10, + 16, and 32. + The more pixel values vary, the smaller this number should be. + For optimal performance, the number of pixels per scan line + (i.e., the size of the fastest-changing dimension in the chunk) + should be an even multiple of the number of pixels per block. +

    +

    Notes: +
    SZIP works only with datasets with 1 through 24 bits/pixel, + 32 pits/pixel, or 64 bits/pixel. +

    + SZIP typically requires that the user application also supply + the number of pixels in the object to be compressed, + the number of bits per pixel, and the number of pixels per scan line. + These values need not be independently supplied in the HDF5 + environment as they are derived from the datatype and dataspace, + which are already known. +

    + Also see + SZIP Compression in HDF5 + for further discussion of SZIP compression in HDF5, + for important information regarding terms of use and + the SZIP copyright notice, + and for a list of SZIP-related references. +

    Parameters:
    -
    hid_t fapl_id -
    IN: File access property list identifier. +
    hid_t plist +
    IN: Dataset creation or dataset transfer property list + identifier. +
    unsigned int options_mask +
    IN: A bit-mask conveying the desired SZIP options. +
    unsigned int pixels_per_block +
    IN: The number of pixels or data elements in each data block.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    + +
    + + + + + + - +
    -
    Name: H5Pset_fapl_stdio +
    Name: H5Pset_meta_block_size
    Signature: -
    herr_t H5Pset_fapl_stdio( - hid_t fapl_id +
    herr_t H5Pset_meta_block_size( + hid_t fapl_id, + hsize_t size )
    Purpose: -
    Sets the standard I/O driver. +
    Sets the minimum metadata block size.
    Description: -
    H5Pset_fapl_stdio modifies the file access property list - to use the standard I/O driver, H5FD_STDIO. +
    H5Pset_meta_block_size sets the + minimum size, in bytes, of metadata block allocations when + H5FD_FEAT_AGGREGATE_METADATA is set by a VFL driver. +

    + Each raw metadata block is initially allocated to be of the + given size. Specific metadata objects (e.g., object headers, + local heaps, B-trees) are then sub-allocated from this block. +

    + The default setting is 2048 bytes, meaning that the library + will attempt to aggregate metadata in at least 2K blocks in the file. + Setting the value to 0 (zero) with this function + will turn off metadata aggregation, even if the VFL driver attempts + to use the metadata aggregation strategy. +

    + Metadata aggregation reduces the number of small data objects + in the file that would otherwise be required for metadata. + The aggregated block of metadata is usually written in a + single write action and always in a contiguous block, + potentially significantly improving library and application + performance.

    Parameters:
    hid_t fapl_id
    IN: File access property list identifier. +
    hsize_t size +
    IN: Minimum size, in bytes, of metadata block allocations.
    Returns:
    Returns a non-negative value if successful. Otherwise returns a negative value.
    Non-C API(s): -
    + + - +
    -
    Name: H5Pset_fapl_stream +
    Name: H5Pset_sieve_buf_size
    Signature: -
    herr_t H5Pset_fapl_stream( +
    herr_t H5Pset_sieve_buf_size( hid_t fapl_id, - H5FD_stream_fapl_t *fapl + hsize_t size )
    Purpose: -
    Sets up the use of the streaming I/O driver. +
    Sets the maximum size of the data sieve buffer.
    Description: -
    H5Pset_fapl_stream sets up the use of the - streaming I/O driver. -

    - fapl_id is the identifier for the - file access property list currently in use. -

    - fapl is the file access property list. +

    H5Pset_sieve_buf_size sets size, + the maximum size in bytes of the data sieve buffer, which is + used by file drivers that are capable of using data sieving.

    - The H5FD_stream_fapl_t struct contains the following - elements: -

    - - - - - - - - - - - - - - - - - - - -
    size_tincrement
    H5FD_STREAM_SOCKET_TYPEsocket
    hbool_tdo_socket_io
    unsigned intbacklog
    H5FD_stream_broadcast_tbroadcast_fn
    void *broadcast_arg
    -
      -
    • increment specifies how much memory to allocate - each time additional memory is required. -
    • socket is an external socket descriptor; - if a valid socket argument is provided, that socket will be used. -
    • do_socket_io is a boolean value specifying whether - to perform I/O on socket. -
    • backlog is the argument for the - listen call. -
    • broadcast_fn is the broadcast callback function. -
    • broadcast_arg is the user argument to - the broadcast callback function. -
    -     + The data sieve buffer is used when performing I/O on datasets + in the file. Using a buffer which is large enough to hold + several pieces of the dataset being read in for + hyperslab selections boosts performance by quite a bit.

    - H5Pset_fapl_stream and H5Pget_fapl_stream - are not intended for use in a parallel environment. + The default value is set to 64KB, indicating that file I/O for + raw data reads and writes will occur in at least 64KB blocks. + Setting the value to 0 with this API function will turn off the + data sieving, even if the VFL driver attempts to use that strategy.

    Parameters:
    hid_t fapl_id
    IN: File access property list identifier. -
    H5FD_stream_fapl_t *fapl -
    IN: The streaming I/O file access property list. +
    hsize_t size +
    IN: Maximum size, in bytes, of data sieve buffer.
    Returns:
    Returns a non-negative value if successful. Otherwise returns a negative value. -
    + + + + + + + + + + + + + + + + + + + + + + + + + + - +
    -
    Name: H5Pget_fapl_stream +
    Name: H5Pset_small_data_block_size
    Signature: -
    herr_t H5Pget_fapl_stream( - hid_t fapl_id, - H5FD_stream_fapl_t *fapl - ) +
    herr_t H5Pset_small_data_block_size(hid_t fapl_id, + hsize_t size + )
    Purpose: -
    Returns the streaming I/O driver settings. +
    Sets the size of a contiguous block reserved for small data.
    Description: -
    H5Pget_fapl_stream returns the file access properties - set for the use of the streaming I/O driver. +
    H5Pset_small_data_block_size reserves blocks of + size bytes for the contiguous storage of the raw data + portion of small datasets. + The HDF5 library then writes the raw data from small datasets + to this reserved space, thus reducing unnecessary discontinuities + within blocks of meta data and improving IO performance. +

    + A small data block is actually allocated the first time a + qualifying small dataset is written to the file. + Space for the raw data portion of this small dataset is suballocated + within the small data block. + The raw data from each subsequent small dataset is also written to + the small data block until it is filled; additional small data blocks + are allocated as required. +

    + The HDF5 library employs an algorithm that determines whether + IO performance is likely to benefit from the use of this mechanism + with each dataset as storage space is allocated in the file. + A larger size will result in this mechanism being + employed with larger datasets.

    - H5Pset_fapl_stream and H5Pget_fapl_stream - are not intended for use in a parallel environment. + The small data block size is set as an allocation property in the + file access property list identified by fapl_id. +

    + Setting size to zero (0) disables the + small data block mechanism.

    Parameters:
    hid_t fapl_id -
    IN: File access property list identifier. -
    H5FD_stream_fapl_t *fapl -
    OUT: The streaming I/O file access property list. +
    IN: File access property list identifier . +
    hsize_t size +
    IN: Maximum size, in bytes, of the small data block. +
    + The default size is 2048.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. - +
    -
    Name: H5Pset_driver +
    Name: H5Pset_preserve
    Signature: -
    herr_t H5Pset_driver( - hid_t plist_id, - hid_t driver_id, - const void * driver_info - ) +
    herr_t H5Pset_preserve(hid_t plist, + hbool_t status + )
    Purpose: -
    Sets the file driver. +
    Sets the dataset transfer property list status to TRUE or FALSE.
    Description: -
    H5Pset_driver sets the file driver, - driver_id, for a file access or data transfer - property list, plist_id, and supplies an - optional struct containing the driver-specific properties, - driver_info. -

    - Need driver_info struct definition. +

    H5Pset_preserve sets the + dataset transfer property list status to TRUE or FALSE.

    - The driver properties will be copied into the property list - and the reference count on the driver will be incremented, - allowing the caller to close the driver identifier but still use - the property list. + When reading or writing compound data types and the + destination is partially initialized and the read/write is + intended to initialize the other members, one must set this + property to TRUE. Otherwise the I/O pipeline treats the + destination datapoints as completely uninitialized.

    Parameters:
    -
    hid_t plist_id -
    IN: File access or data transfer property list identifier. -
    hid_t driver_id -
    IN: Driver identifier. -
    const void * driver_info -
    IN: Optional struct containing driver properties. +
    hid_t plist +
    IN: Identifier for the dataset transfer property list. +
    hbool_t status +
    IN: Status of for the dataset transfer property list + (TRUE/FALSE).
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    +
    ---> - - + + +
    +--> + - - - + + + + -
    +--> + - +
    -
    Name: H5Pget_fapl_gass +
    Name: H5Pset_vlen_mem_manager
    Signature: -
    herr_t H5Pget_fapl_gass( - hid_t fapl_id, - GASS_Info *info +
    herr_t H5Pset_vlen_mem_manager(hid_t plist, + H5MM_allocate_t alloc, + void *alloc_info, + H5MM_free_t free, + void *free_info )
    Purpose: -
    Retrieves GASS information. +
    Sets the memory manager for variable-length datatype allocation in + H5Dread and H5Dvlen_reclaim.
    Description: -
    If the file access property list fapl_id is set - for use of the H5FD_GASS driver, - H5Pget_fapl_gass returns the GASS_Info - object through the info pointer. +
    H5Pset_vlen_mem_manager sets the memory manager for + variable-length datatype allocation in H5Dread + and free in H5Dvlen_reclaim.

    - The GASS_Info information is copied, so it is valid - only until the file access property list is modified or closed. -

    Note: -
    H5Pget_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - GASS facility of the Globus environment. - For further information, see - http//www.globus.org/. + The alloc and free parameters + identify the memory management routines to be used. + If the user has defined custom memory management routines, + alloc and/or free should be set to make + those routine calls (i.e., the name of the routine is used as + the value of the parameter); + if the user prefers to use the system's malloc + and/or free, the alloc and + free parameters, respectively, should be set to + NULL +

    + The prototypes for these user-defined functions would appear as follows: +
         + typedef void *(*H5MM_allocate_t)(size_t size, + void *alloc_info) ; + +
         + typedef void (*H5MM_free_t)(void *mem, + void *free_info) ; +
    + The alloc_info and free_info parameters + can be used to pass along any required information to + the user's memory management routines. +

    + In summary, if the user has defined custom memory management + routines, the name(s) of the routines are passed in the + alloc and free parameters and the + custom routines' parameters are passed in the + alloc_info and free_info parameters. + If the user wishes to use the system malloc and + free functions, the alloc and/or + free parameters are set to NULL + and the alloc_info and free_info + parameters are ignored.

    Parameters:
    -
    hid_t fapl_id, -
    IN: File access property list identifier. -
    GASS_Info *info -
    OUT: Pointer to the GASS information structure. +
    hid_t plist +
    IN: Identifier for the dataset transfer property list. +
    H5MM_allocate_t alloc +
    IN: User's allocate routine, or   NULL + for system   malloc. +
    void *alloc_info +
    IN: Extra parameter for user's allocation routine. +
    + Contents are ignored if preceding parameter is   + NULL. +
    H5MM_free_t free +
    IN: User's free routine, or   NULL + for system free. +
    void *free_info +
    IN: Extra parameter for user's free routine. +
    + Contents are ignored if preceding parameter is   + NULL.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value. -
    + + + + + + + + + + + + + + + + + + + + + - +
    -
    Name: H5Pset_fapl_srb +
    Name: H5Pget_fapl_mpio
    Signature: -
    herr_t H5Pset_fapl_srb( +
    herr_t H5Pset_fapl_mpiposix( hid_t fapl_id, - SRB_Info info + MPI_Comm comm )
    Purpose: -
    Saves SRB connection handler and sets SRB settings. +
    Stores MPI IO communicator information to a file access property list.
    Description: -
    H5Pset_fapl_srb stores the SRB client-to-server - connection handler SRB_CONN after the connection - is established and other user-supplied SRB information. +
    H5Pset_fapl_mpiposix stores the user-supplied + MPI IO parameter comm, for communicator, + in the file access property list fapl_id. + That property list can then be used to create and/or open the file.

    - The user-supplied SRB information is contained in the - SRB_Info struct pointed to by info - and is stored in the file access property list fapl_id. - This information can then be used to create or open a file. -

    Note: -
    H5Pset_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - Storage Resource Broker (SRB). For further information, see - http//www.npaci.edu/Research/DI/srb/. + H5Pset_fapl_mpiposix is available only in the + parallel HDF5 library and is not a collective function. +

    + comm is the MPI communicator to be used for + file open as defined in MPI_FILE_OPEN of MPI-2. + This function does not create a duplicated communicator. + Modifications to comm after this function call + returns may have an undetermined effect on the access property list. + Users should not modify the communicator while it is defined + in a property list.

    Parameters:
    hid_t fapl_id
    IN: File access property list identifier. -
    SRB_Info info -
    IN: Pointer to the SRB information structure. +
    MPI_Comm comm +
    IN: MPI-2 communicator.
    Returns:
    Returns a non-negative value if successful. Otherwise returns a negative value. - -
    + + + + + + + + + + + + + + + + - +
    -
    Name: H5Pget_fapl_srb +
    Name: H5Pset_multi_type
    Signature: -
    herr_t H5Pget_fapl_srb( - hid_t fapl_id, - SRB_Info *info +
    herr_t H5Pset_multi_type ( + hid_t fapl_id, + H5FD_mem_t type )
    Purpose: -
    Retrieves SRB information. +
    Sets data type property for MULTI driver.
    Description: -
    If the file access property list fapl_id is set - for use of the H5FD_SRB driver, - H5Pget_fapl_srb returns the SRB_Info - object through the info pointer. -

    - The SRB_Info information is copied, so it is valid - only until the file access property list is modified or closed. -

    Note: -
    H5Pset_fapl_gass is an experimental function. - It is designed for use only when accessing files via the - Storage Resource Broker (SRB). For further information, see - http//www.npaci.edu/Research/DI/srb/. +
    H5Pset_multi_type sets the data type property in the + file access or data transfer property list fapl_id. + This enables a user application to specifiy the type of data the + appication wishes to access so that the application + can retrieve a file handle for low-level access to the particular member + of a set of MULTI files in which that type of data is stored. + The file handle is retrieved with a separate call + to H5Fget_vfd_handle + (or, in special circumstances, to H5FDget_vfd_handle; + see Virtual File Layer and List of VFL Functions + in HDF5 Technical Notes). +

    + The type of data specified in type may be one of the following: + + + + + + + + +
         + H5FD_MEM_DEFAULT   + + Need description.... +
      + H5FD_MEM_SUPER + + Super block ... need description.... +
      + H5FD_MEM_BTREE + + Btree ... need description.... +
      + H5FD_MEM_DRAW + + Need description.... +
      + H5FD_MEM_GHEAP + + Global heap ... need description.... +
      + H5FD_MEM_LHEAP + + Local Heap ... need description.... +
      + H5FD_MEM_OHDR + + Need description.... +
    +

    + Use of this function is only appropriate for an HDF5 file written + as a set of files with the MULTI file driver.

    Parameters:
    hid_t fapl_id -
    IN: File access property list identifier. -
    SRB_Info *info -
    OUT: Pointer to the SRB information structure. +
    IN: File access property list or data transfer property list identifier. +
    H5FD_mem_t type +
    OUT: Type of data.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    - - + + + + + + + + + + + + - - -
    -
    -
    Name: H5Pget_fapl_core -
    Signature: -
    herr_t H5Pget_fapl_core( - hid_t fapl_id, - size_t *increment, - hbool_t *backing_store - ) -
    Purpose: -
    Queries core file driver properties. -
    Description: -
    H5Pget_fapl_core queries the H5FD_CORE - driver properties as set by H5Pset_fapl_core. -
    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    size_t *increment -
    OUT: Size, in bytes, of memory increments. -
    hbool_t *backing_store -
    OUT: Boolean flag indicating whether to write the file - contents to disk when the file is closed. -
    -
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value. -
    Non-C API(s): -
    - -
    +--> + + + + + + + + + + + + + + + + + + + - - -
    -
    -
    Name: H5Pset_fclose_degree -
    Signature: -
    herr_t H5Pset_fclose_degree(hid_t fapl_id, - H5F_close_degree_t fc_degree) -
    Purpose: -
    Sets the file close degree. -
    Description: -
    H5Pset_fclose_degree sets the file close degree property fc_degree - in the file access property list fapl_id.  -

    The value of fc_degree determines how aggressively H5Fclose - deals with objects within a file that remain open when H5Fclose - is called to close that file.  fc_degree can have any one of - four valid values: -

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    Degree nameH5Fclose behavior with no open object - in fileH5Fclose behavior with open object(s) - in file
    H5F_CLOSE_WEAKActual file is closed.Access to file identifier is terminated; actual file - close is delayed until all objects in file are closed
    H5F_CLOSE_SEMIActual file is closed.Function returns FAILURE
    H5F_CLOSE_STRONGActual file is closed.All open objects ramaining in the file are closed then - file is closed
    H5F_CLOSE_DEFAULTThe VFL driver chooses the behavior.  Currently, - all VFL drivers set this value to H5F_CLOSE_WEAK, except - for the MPI-I/O driver, which sets it to H5F_CLOSE_SEMI. -
    -
    -
    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    H5F_close_degree_t fc_degree -
    IN: Pointer to a location containing the file close degree property, - the value of fc_degree. -
    -
    Returns: -
    Returns a non-negative value if successful. Otherwise returns a negative - value. -
    Non-C API(s): -
    - -
    - - -
    -
    -
    Name: H5Pget_fclose_degree -
    Signature: -
    herr_t H5Pget_fclose_degree(hid_t fapl_id, - H5F_close_degree_t fc_degree) -
    Purpose: -
    Returns the file close degree. -
    Description: -
    H5Pget_fclose_degree returns the current setting of the file - close degree property fc_degree in the file access property list - fapl_id.  -

    The value of fc_degree determines how aggressively H5Fclose - deals with objects within a file that remain open when H5Fclose - is called to close that file.  fc_degree can have any one of - four valid values as described above in H5Pset_fclose_degree. -

    Parameters: -
    -
    hid_t fapl_id -
    IN: File access property list identifier. -
    H5F_close_degree_t fc_degree -
    OUT: Pointer to a location to which to return the file close degree - property, the value of fc_degree. -
    -
    Returns: -
    Returns a non-negative value if successful. Otherwise returns a negative - value. -
    Non-C API(s): -
    - -
    +
    HDF Help Desk
    Describes HDF5 Release 1.6.0, July 2003
    diff --git a/doc/html/RM_H5R.html b/doc/html/RM_H5R.html index 138afbd..c1b95a8 100644 --- a/doc/html/RM_H5R.html +++ b/doc/html/RM_H5R.html @@ -61,8 +61,7 @@ And in this document, the -
    -
    +

    H5R: Reference Interface

    @@ -279,51 +278,6 @@ facilitate moving easily between them. - -
    -
    -
    Name: H5Rget_region -
    Signature: -
    hid_t H5Rget_region(hid_t dataset, - H5R_type_t ref_type, - void *ref - ) -
    Purpose: -
    Retrieves a dataspace with the specified region selected. -
    Description: -
    Given a reference to an object ref, - H5Rget_region creates a copy of the dataspace - of the dataset pointed to and defines a selection in the copy - which is the region pointed to. -

    - The parameter ref_type specifies the reference type - of ref. - ref_type may contain the following value: -

      -
    • H5R_DATASET_REGION (1) -
    -
    Parameters: -
    -
    hid_t dataset, -
    IN: Dataset containing reference object. -
    H5R_type_t ref_type, -
    IN: The reference type of ref. -
    void *ref -
    IN: Reference to open. -
    -
    Returns: -
    Returns a valid identifier if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - -
    @@ -443,6 +397,50 @@ facilitate moving easily between them. -->
    + + +
    +
    +
    Name: H5Rget_region +
    Signature: +
    hid_t H5Rget_region(hid_t dataset, + H5R_type_t ref_type, + void *ref + ) +
    Purpose: +
    Retrieves a dataspace with the specified region selected. +
    Description: +
    Given a reference to an object ref, + H5Rget_region creates a copy of the dataspace + of the dataset pointed to and defines a selection in the copy + which is the region pointed to. +

    + The parameter ref_type specifies the reference type + of ref. + ref_type may contain the following value: +

      +
    • H5R_DATASET_REGION (1) +
    +
    Parameters: +
    +
    hid_t dataset, +
    IN: Dataset containing reference object. +
    H5R_type_t ref_type, +
    IN: The reference type of ref. +
    void *ref +
    IN: Reference to open. +
    +
    Returns: +
    Returns a valid identifier if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    @@ -477,14 +475,13 @@ And in this document, the
    -
    -
    +
    HDF Help Desk
    Describes HDF5 Release 1.6.0, July 2003
    diff --git a/doc/html/RM_H5S.html b/doc/html/RM_H5S.html index 679c9af..7bb5286 100644 --- a/doc/html/RM_H5S.html +++ b/doc/html/RM_H5S.html @@ -61,8 +61,7 @@ And in this document, the
    -
    -
    +

    H5S: Dataspace Interface

    @@ -244,6 +243,70 @@ of the HDF5 User's Guide.. + +
    +
    +
    Name: H5Sclose +
    Signature: +
    herr_t H5Sclose(hid_t space_id + ) +
    Purpose: +
    Releases and terminates access to a dataspace. +
    Description: +
    H5Sclose releases a dataspace. + Further access through the dataspace identifier is illegal. + Failure to release a dataspace with this call will + result in resource leaks. +
    Parameters: +
    +
    hid_t space_id +
    Identifier of dataspace to release. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Scopy +
    Signature: +
    hid_t H5Scopy(hid_t space_id + ) +
    Purpose: +
    Creates an exact copy of a dataspace. +
    Description: +
    H5Scopy creates a new dataspace which is an exact + copy of the dataspace identified by space_id. + The dataspace identifier returned from this function should be + released with H5Sclose or resource leaks will occur. +
    Parameters: +
    +
    hid_t space_id +
    Identifier of dataspace to copy. +
    +
    Returns: +
    Returns a dataspace identifier if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + +
    @@ -331,30 +394,34 @@ of the HDF5 User's Guide..
    - +
    -
    Name: H5Scopy +
    Name: H5Sextent_copy
    Signature: -
    hid_t H5Scopy(hid_t space_id +
    herr_t H5Sextent_copy(hid_t dest_space_id, + hid_t source_space_id )
    Purpose: -
    Creates an exact copy of a dataspace. +
    Copies the extent of a dataspace.
    Description: -
    H5Scopy creates a new dataspace which is an exact - copy of the dataspace identified by space_id. - The dataspace identifier returned from this function should be - released with H5Sclose or resource leaks will occur. +
    H5Sextent_copy copies the extent from + source_space_id to dest_space_id. + This action may change the type of the dataspace.
    Parameters:
    -
    hid_t space_id -
    Identifier of dataspace to copy. +
    hid_t dest_space_id +
    IN: The identifier for the dataspace to which + the extent is copied. +
    hid_t source_space_id +
    IN: The identifier for the dataspace from which + the extent is copied.
    Returns: -
    Returns a dataspace identifier if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sselect_elements +
    Name: H5Sget_select_bounds
    Signature: -
    herr_t H5Sselect_elements(hid_t space_id, - H5S_seloper_t op, - const size_t num_elements, - const hssize_t *coord[ ] +
    herr_t H5Sget_select_bounds(hid_t space_id, + hssize_t *start, + hssize_t *end )
    Purpose: -
    Selects array elements to be included in the selection for a dataspace. +
    Gets the bounding box containing the current selection.
    Description: -
    H5Sselect_elements selects array elements to be - included in the selection for the space_id - dataspace. The number of elements selected must be set with - the num_elements. The coord array - is a two-dimensional array of size dataspace rank - by num_elements (ie. a list of coordinates in - the array). The order of the element coordinates in the - coord array also specifies the order in which - the array elements are iterated through when I/O is performed. - Duplicate coordinate locations are not checked for. +
    H5Sget_select_bounds retrieves the coordinates of + the bounding box containing the current selection and places + them into user-supplied buffers.

    - The selection operator op determines how the - new selection is to be combined with the previously existing - selection for the dataspace. - The following operators are supported: -

    - - -
    - H5S_SELECT_SET - - Replaces the existing selection with the parameters from this call. - Overlapping blocks are not supported with this operator. - Adds the new selection to the existing selection. -
    - H5S_SELECT_APPEND - - Adds the new selection following the last element of the existing selection. -
    - H5S_SELECT_PREPEND   - - Adds the new selection preceding the first element of the existing selection. -
    -
    - + The start and end buffers must be large + enough to hold the dataspace rank number of coordinates. +

    + The bounding box exactly contains the selection. + I.e., if a 2-dimensional element selection is currently + defined as containing the points (4,5), (6,8), and (10,7), + then the bounding box will be (4, 5), (10, 8). +

    + The bounding box calculation includes the current offset of the + selection within the dataspace extent. +

    + Calling this function on a none selection will + return FAIL.

    Parameters:
    hid_t space_id -
    Identifier of the dataspace. -
    H5S_seloper_t op -
    operator specifying how the new selection is to be - combined with the existing selection for the dataspace. -
    const size_t num_elements -
    Number of elements to be selected. -
    const hssize_t *coord[ ] -
    A 2-dimensional array specifying the coordinates of the - elements being selected. +
    IN: Identifier of dataspace to query. +
    hssize_t *start +
    OUT: Starting coordinates of the bounding box. +
    hssize_t *end +
    OUT: Ending coordinates of the bounding box, + i.e., the coordinates of the diagonally opposite corner.
    Returns: -
    Returns a non-negative value if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value. +
    - +
    -
    Name: H5Sselect_all +
    Name: H5Sget_select_elem_npoints
    Signature: -
    herr_t H5Sselect_all(hid_t space_id) +
    hssize_t H5Sget_select_elem_npoints(hid_t space_id + )
    Purpose: -
    Selects the entire dataspace. +
    Gets the number of element points in the current selection.
    Description: -
    H5Sselect_all selects the entire extent - of the dataspace space_id. -

    - More specifically, H5Sselect_all selects - the special 5S_SELECT_ALL region for the dataspace - space_id. H5S_SELECT_ALL selects the - entire dataspace for any dataspace it is applied to. +

    H5Sget_select_elem_npoints returns + the number of element points in the current dataspace selection.
    Parameters:
    hid_t space_id -
    IN: The identifier for the dataspace in which the - selection is being made. +
    IN: Identifier of dataspace to query.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns the number of element points in the current dataspace selection if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sselect_none +
    Name: H5Sget_select_elem_pointlist
    Signature: -
    herr_t H5Sselect_none(hid_t space_id) +
    herr_t H5Sget_select_elem_pointlist(hid_t space_id, + hsize_t startpoint, + hsize_t numpoints, + hsize_t *buf + )
    Purpose: -
    Resets the selection region to include no elements. +
    Gets the list of element points currently selected.
    Description: -
    H5Sselect_none resets the selection region - for the dataspace space_id to include no elements. +
    H5Sget_select_elem_pointlist returns the list of + element points in the current dataspace selection. Starting with + the startpoint-th point in the list of points, + numpoints points are put into the user's buffer. + If the user's buffer fills up before numpoints + points are inserted, the buffer will contain only as many + points as fit. +

    + The element point coordinates have the same dimensionality (rank) + as the dataspace they are located within. The list of element points + is formatted as follows: +
         + <coordinate>, followed by +
         + the next coordinate, +
         + etc. +
    + until all of the selected element points have been listed. +

    + The points are returned in the order they will be iterated through + when the selection is read/written from/to disk.

    Parameters:
    hid_t space_id -
    IN: The identifier for the dataspace in which the - selection is being reset. +
    IN: Dataspace identifier of selection to query. +
    hsize_t startpoint +
    IN: Element point to start with. +
    hsize_t numpoints +
    IN: Number of element points to get. +
    hsize_t *buf +
    OUT: List of element points selected.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sselect_valid +
    Name: H5Sget_select_hyper_blocklist
    Signature: -
    htri_t H5Sselect_valid(hid_t space_id) +
    herr_t H5Sget_select_hyper_blocklist(hid_t space_id, + hsize_t startblock, + hsize_t numblocks, + hsize_t *buf + )
    Purpose: -
    Verifies that the selection is within the extent of the dataspace. +
    Gets the list of hyperslab blocks currently selected.
    Description: -
    H5Sselect_valid verifies that the selection - for the dataspace space_id is within the extent - of the dataspace if the current offset for the dataspace is used. +
    H5Sget_select_hyper_blocklist returns a list of + the hyperslab blocks currently selected. Starting with the + startblock-th block in the list of blocks, + numblocks blocks are put into the user's buffer. + If the user's buffer fills up before numblocks + blocks are inserted, the buffer will contain only as many + blocks as fit. +

    + The block coordinates have the same dimensionality (rank) + as the dataspace they are located within. The list of blocks + is formatted as follows: +
         + <"start" coordinate>, immediately followed by +
         + <"opposite" corner coordinate>, followed by +
         + the next "start" and "opposite" coordinates, +
         + etc. +
    + until all of the selected blocks have been listed. +

    + No guarantee is implied as the order in which blocks are listed.

    Parameters:
    hid_t space_id -
    The identifier for the dataspace being queried. +
    IN: Dataspace identifier of selection to query. +
    hsize_t startblock +
    IN: Hyperslab block to start with. +
    hsize_t numblocks +
    IN: Number of hyperslab blocks to get. +
    hsize_t *buf +
    OUT: List of hyperslab blocks selected.
    Returns: -
    Returns a positive value, for TRUE, - if the selection is contained within the extent - or 0 (zero), for FALSE, if it is not. - Returns a negative value on error conditions - such as the selection or extent not being defined. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_simple_extent_npoints +
    Name: H5Sget_select_hyper_nblocks
    Signature: -
    hssize_t H5Sget_simple_extent_npoints(hid_t space_id) +
    hssize_t H5Sget_select_hyper_nblocks(hid_t space_id + )
    Purpose: -
    Determines the number of elements in a dataspace. +
    Get number of hyperslab blocks.
    Description: -
    H5Sget_simple_extent_npoints 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. +
    H5Sget_select_hyper_nblocks returns the + number of hyperslab blocks in the current dataspace selection.
    Parameters:
    hid_t space_id -
    ID of the dataspace object to query +
    IN: Identifier of dataspace to query.
    Returns: -
    Returns the number of elements in the dataspace if successful; - otherwise returns 0. +
    Returns the number of hyperslab blocks in + the current dataspace selection if successful. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_simple_extent_ndims +
    Name: H5Sget_select_type
    Signature: -
    int H5Sget_simple_extent_ndims(hid_t space_id) +
    H5S_sel_type H5Sget_select_type(hid_t space_id)
    Purpose: -
    Determines the dimensionality of a dataspace. +
    Determines the type of the dataspace selection.
    Description: -
    H5Sget_simple_extent_ndims determines the dimensionality (or rank) - of a dataspace. +
    H5Sget_select_type retrieves the + type of selection currently defined for the dataspace + space_id.
    Parameters:
    hid_t space_id -
    Identifier of the dataspace +
    Dataspace identifier.
    Returns: -
    Returns the number of dimensions in the dataspace if successful; - otherwise returns a negative value. +
    Returns the dataspace selection type, a value of + the enumerated datatype H5S_sel_type, + if successful. + Valid return values are as follows: +
    + + +
    + H5S_SEL_NONE + + No selection is defined. +
    + H5S_SEL_POINTS + + A sequence of points is selected. +
    + H5S_SEL_HYPERSLABS + + A hyperslab or compound hyperslab is selected. +
    + H5S_SEL_ALL + + The entire dataset is selected. +
    +
    + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_simple_extent_type +
    Name: H5Sget_simple_extent_ndims
    Signature: -
    H5S_class_t H5Sget_simple_extent_type(hid_t space_id) +
    int H5Sget_simple_extent_ndims(hid_t space_id)
    Purpose: -
    Determine the current class of a dataspace. +
    Determines the dimensionality of a dataspace.
    Description: -
    H5Sget_simple_extent_type queries a dataspace to determine the - current class of a dataspace. -

    - The function returns a class name, one of the following: - H5S_SCALAR, - H5S_SIMPLE, or - H5S_NONE. +

    H5Sget_simple_extent_ndims determines the dimensionality (or rank) + of a dataspace.
    Parameters:
    hid_t space_id -
    Dataspace identifier. +
    Identifier of the dataspace
    Returns: -
    Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). +
    Returns the number of dimensions in the dataspace if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sset_extent_simple +
    Name: H5Sget_simple_extent_npoints
    Signature: -
    herr_t H5Sset_extent_simple(hid_t space_id, - int rank, - const hsize_t *current_size, - const hsize_t *maximum_size - ) +
    hssize_t H5Sget_simple_extent_npoints(hid_t space_id)
    Purpose: -
    Sets or resets the size of an existing dataspace. +
    Determines the number of elements in a dataspace.
    Description: -
    H5Sset_extent_simple sets or resets the size of - an existing dataspace. -

    - rank is the dimensionality, or number of - dimensions, of the dataspace. -

    - current_size is an array of size rank - which contains the new size of each dimension in the dataspace. - maximum_size is an array of size rank - which contains the maximum size of each dimension in the - dataspace. +

    H5Sget_simple_extent_npoints 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: +
    Returns the number of elements in the dataspace if successful; + otherwise returns 0. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Sget_simple_extent_type +
    Signature: +
    H5S_class_t H5Sget_simple_extent_type(hid_t space_id) +
    Purpose: +
    Determine the current class of a dataspace. +
    Description: +
    H5Sget_simple_extent_type queries a dataspace to determine the + current class of a dataspace.

    - Any previous extent is removed from the dataspace, the dataspace - type is set to H5S_SIMPLE, and the extent is set as - specified. + The function returns a class name, one of the following: + H5S_SCALAR, + H5S_SIMPLE, or + H5S_NONE.

    Parameters:
    hid_t space_id
    Dataspace identifier. -
    int rank -
    Rank, or dimensionality, of the dataspace. -
    const hsize_t *current_size -
    Array containing current size of dataspace. -
    const hsize_t *maximum_size -
    Array containing maximum size of dataspace.
    Returns: -
    Returns a dataspace identifier if successful; - otherwise returns a negative value. +
    Returns a dataspace class name if successful; + otherwise H5S_NO_CLASS (-1).
    Non-C API(s): -
    - - +
    -
    Name: H5Sextent_class +
    Name: H5Sselect_all
    Signature: -
    H5S_class_t H5Sextent_class(hid_t space_id) +
    herr_t H5Sselect_all(hid_t space_id)
    Purpose: -
    Determine the current class of a dataspace. +
    Selects the entire dataspace.
    Description: -
    H5Sextent_class queries a dataspace to determine the - current class of a dataspace. -

    - The function returns a class name, one of the following: - H5S_SCALAR, - H5S_SIMPLE. +

    H5Sselect_all selects the entire extent + of the dataspace space_id. +

    + More specifically, H5Sselect_all selects + the special 5S_SELECT_ALL region for the dataspace + space_id. H5S_SELECT_ALL selects the + entire dataspace for any dataspace it is applied to.

    Parameters:
    hid_t space_id -
    Dataspace identifier. +
    IN: The identifier for the dataspace in which the + selection is being made.
    Returns: -
    Returns a dataspace class name if successful; - otherwise H5S_NO_CLASS (-1). +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - - -
    - ---> - - - -
    -
    -
    Name: H5Sextent_copy -
    Signature: -
    herr_t H5Sextent_copy(hid_t dest_space_id, - hid_t source_space_id - ) -
    Purpose: -
    Copies the extent of a dataspace. -
    Description: -
    H5Sextent_copy copies the extent from - source_space_id to dest_space_id. - This action may change the type of the dataspace. -
    Parameters: -
    -
    hid_t dest_space_id -
    IN: The identifier for the dataspace to which - the extent is copied. -
    hid_t source_space_id -
    IN: The identifier for the dataspace from which - the extent is copied. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - +
    -
    Name: H5Sset_extent_none +
    Name: H5Sselect_elements
    Signature: -
    herr_t H5Sset_extent_none(hid_t space_id) +
    herr_t H5Sselect_elements(hid_t space_id, + H5S_seloper_t op, + const size_t num_elements, + const hssize_t *coord[ ] + )
    Purpose: -
    Removes the extent from a dataspace. +
    Selects array elements to be included in the selection for a dataspace.
    Description: -
    H5Sset_extent_none removes the extent from - a dataspace and sets the type to H5S_NO_CLASS. +
    H5Sselect_elements selects array elements to be + included in the selection for the space_id + dataspace. The number of elements selected must be set with + the num_elements. The coord array + is a two-dimensional array of size dataspace rank + by num_elements (ie. a list of coordinates in + the array). The order of the element coordinates in the + coord array also specifies the order in which + the array elements are iterated through when I/O is performed. + Duplicate coordinate locations are not checked for. +

    + The selection operator op determines how the + new selection is to be combined with the previously existing + selection for the dataspace. + The following operators are supported: +

    + + +
    + H5S_SELECT_SET + + Replaces the existing selection with the parameters from this call. + Overlapping blocks are not supported with this operator. + Adds the new selection to the existing selection. +
    + H5S_SELECT_APPEND + + Adds the new selection following the last element of the existing selection. +
    + H5S_SELECT_PREPEND   + + Adds the new selection preceding the first element of the existing selection. +
    +
    +
    Parameters:
    hid_t space_id -
    The identifier for the dataspace from which - the extent is to be removed. +
    Identifier of the dataspace. +
    H5S_seloper_t op +
    operator specifying how the new selection is to be + combined with the existing selection for the dataspace. +
    const size_t num_elements +
    Number of elements to be selected. +
    const hssize_t *coord[ ] +
    A 2-dimensional array specifying the coordinates of the + elements being selected.
    Returns: -
    Returns a non-negative value if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_select_hyper_nblocks +
    Name: H5Sselect_none
    Signature: -
    hssize_t H5Sget_select_hyper_nblocks(hid_t space_id - ) +
    herr_t H5Sselect_none(hid_t space_id)
    Purpose: -
    Get number of hyperslab blocks. +
    Resets the selection region to include no elements.
    Description: -
    H5Sget_select_hyper_nblocks returns the - number of hyperslab blocks in the current dataspace selection. +
    H5Sselect_none resets the selection region + for the dataspace space_id to include no elements.
    Parameters:
    hid_t space_id -
    IN: Identifier of dataspace to query. +
    IN: The identifier for the dataspace in which the + selection is being reset.
    Returns: -
    Returns the number of hyperslab blocks in - the current dataspace selection if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_select_hyper_blocklist +
    Name: H5Sselect_valid
    Signature: -
    herr_t H5Sget_select_hyper_blocklist(hid_t space_id, - hsize_t startblock, - hsize_t numblocks, - hsize_t *buf - ) +
    htri_t H5Sselect_valid(hid_t space_id)
    Purpose: -
    Gets the list of hyperslab blocks currently selected. +
    Verifies that the selection is within the extent of the dataspace.
    Description: -
    H5Sget_select_hyper_blocklist returns a list of - the hyperslab blocks currently selected. Starting with the - startblock-th block in the list of blocks, - numblocks blocks are put into the user's buffer. - If the user's buffer fills up before numblocks - blocks are inserted, the buffer will contain only as many - blocks as fit. -

    - The block coordinates have the same dimensionality (rank) - as the dataspace they are located within. The list of blocks - is formatted as follows: -
         - <"start" coordinate>, immediately followed by -
         - <"opposite" corner coordinate>, followed by -
         - the next "start" and "opposite" coordinates, -
         - etc. -
    - until all of the selected blocks have been listed. -

    - No guarantee is implied as the order in which blocks are listed. +

    H5Sselect_valid verifies that the selection + for the dataspace space_id is within the extent + of the dataspace if the current offset for the dataspace is used.
    Parameters:
    hid_t space_id -
    IN: Dataspace identifier of selection to query. -
    hsize_t startblock -
    IN: Hyperslab block to start with. -
    hsize_t numblocks -
    IN: Number of hyperslab blocks to get. -
    hsize_t *buf -
    OUT: List of hyperslab blocks selected. +
    The identifier for the dataspace being queried.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a positive value, for TRUE, + if the selection is contained within the extent + or 0 (zero), for FALSE, if it is not. + Returns a negative value on error conditions + such as the selection or extent not being defined.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_select_elem_npoints +
    Name: H5Sset_extent_none
    Signature: -
    hssize_t H5Sget_select_elem_npoints(hid_t space_id - ) +
    herr_t H5Sset_extent_none(hid_t space_id)
    Purpose: -
    Gets the number of element points in the current selection. +
    Removes the extent from a dataspace.
    Description: -
    H5Sget_select_elem_npoints returns - the number of element points in the current dataspace selection. +
    H5Sset_extent_none removes the extent from + a dataspace and sets the type to H5S_NO_CLASS.
    Parameters:
    hid_t space_id -
    IN: Identifier of dataspace to query. +
    The identifier for the dataspace from which + the extent is to be removed.
    Returns: -
    Returns the number of element points in the current dataspace selection if successful. - Otherwise returns a negative value. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Sget_select_elem_pointlist +
    Name: H5Sset_extent_simple
    Signature: -
    herr_t H5Sget_select_elem_pointlist(hid_t space_id, - hsize_t startpoint, - hsize_t numpoints, - hsize_t *buf +
    herr_t H5Sset_extent_simple(hid_t space_id, + int rank, + const hsize_t *current_size, + const hsize_t *maximum_size )
    Purpose: -
    Gets the list of element points currently selected. +
    Sets or resets the size of an existing dataspace.
    Description: -
    H5Sget_select_elem_pointlist returns the list of - element points in the current dataspace selection. Starting with - the startpoint-th point in the list of points, - numpoints points are put into the user's buffer. - If the user's buffer fills up before numpoints - points are inserted, the buffer will contain only as many - points as fit. +
    H5Sset_extent_simple sets or resets the size of + an existing dataspace.

    - The element point coordinates have the same dimensionality (rank) - as the dataspace they are located within. The list of element points - is formatted as follows: -
         - <coordinate>, followed by -
         - the next coordinate, -
         - etc. -
    - until all of the selected element points have been listed. + rank is the dimensionality, or number of + dimensions, of the dataspace.

    - The points are returned in the order they will be iterated through - when the selection is read/written from/to disk. + current_size is an array of size rank + which contains the new size of each dimension in the dataspace. + maximum_size is an array of size rank + which contains the maximum size of each dimension in the + dataspace. +

    + Any previous extent is removed from the dataspace, the dataspace + type is set to H5S_SIMPLE, and the extent is set as + specified.

    Parameters:
    hid_t space_id -
    IN: Dataspace identifier of selection to query. -
    hsize_t startpoint -
    IN: Element point to start with. -
    hsize_t numpoints -
    IN: Number of element points to get. -
    hsize_t *buf -
    OUT: List of element points selected. +
    Dataspace identifier. +
    int rank +
    Rank, or dimensionality, of the dataspace. +
    const hsize_t *current_size +
    Array containing current size of dataspace. +
    const hsize_t *maximum_size +
    Array containing maximum size of dataspace.
    Returns: -
    Returns a non-negative value if successful; +
    Returns a dataspace identifier if successful; otherwise returns a negative value.
    Non-C API(s): -
    - - + +
    - - - - +--> - - -
    -
    -
    Name: H5Sget_select_type -
    Signature: -
    H5S_sel_type H5Sget_select_type(hid_t space_id) -
    Purpose: -
    Determines the type of the dataspace selection. -
    Description: -
    H5Sget_select_type retrieves the - type of selection currently defined for the dataspace - space_id. -
    Parameters: -
    -
    hid_t space_id -
    Dataspace identifier. -
    -
    Returns: -
    Returns the dataspace selection type, a value of - the enumerated datatype H5S_sel_type, - if successful. - Valid return values are as follows: -
    - - -
    - H5S_SEL_NONE - - No selection is defined. -
    - H5S_SEL_POINTS - - A sequence of points is selected. -
    - H5S_SEL_HYPERSLABS - - A hyperslab or compound hyperslab is selected. -
    - H5S_SEL_ALL - - The entire dataset is selected. -
    -
    - Otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - -
    -
    -
    Name: H5Sclose -
    Signature: -
    herr_t H5Sclose(hid_t space_id - ) -
    Purpose: -
    Releases and terminates access to a dataspace. -
    Description: -
    H5Sclose releases a dataspace. - Further access through the dataspace identifier is illegal. - Failure to release a dataspace with this call will - result in resource leaks. -
    Parameters: -
    -
    hid_t space_id -
    Identifier of dataspace to release. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    -
    @@ -1473,14 +1467,13 @@ And in this document, the
    -
    -
    +
    HDF Help Desk
    Describes HDF5 Release 1.6.0, July 2003
    diff --git a/doc/html/RM_H5T.html b/doc/html/RM_H5T.html index de24e6c..d5c8fdc 100644 --- a/doc/html/RM_H5T.html +++ b/doc/html/RM_H5T.html @@ -61,8 +61,7 @@ And in this document, the
    -
    -
    +

    H5T: Datatype Interface

    @@ -386,34 +385,87 @@ in the HDF5 User's Guide for further information, including a compl - +
    -
    Name: H5Topen +
    Name: H5Tarray_create
    Signature: -
    hid_tH5Topen(hid_t loc_id, - const char * name +
    hid_t H5Tarray_create( + hid_t base, + int rank, + const hsize_t dims[/*rank*/], + const int perm[/*rank*/] )
    Purpose: -
    Opens a named datatype. +
    Creates an array datatype object.
    Description: -
    H5Topen opens a named datatype at the location - specified by loc_id and returns an identifier - for the datatype. loc_id is either a file or - group identifier. The identifier should eventually be closed - by calling H5Tclose to release resources. +
    H5Tarray_create creates a new array datatype object. +

    + base is the datatype of every element of the array, + i.e., of the number at each position in the array. +

    + rank is the number of dimensions and the + size of each dimension is specified in the array dims. + The value of rank is currently limited to + H5S_MAX_RANK and must be greater than 0 + (zero). + All dimension sizes specified in dims must be greater + than 0 (zero). +

    + The array perm is designed to contain the dimension + permutation, i.e. C versus FORTRAN array order. +   + (The parameter perm is currently unused and is not yet implemented.) +

    Parameters:
    -
    hid_t loc_id -
    IN: A file or group identifier. -
    const char * name -
    IN: A datatype name, defined within the file or group identified by loc_id. +
    hid_t base +
    IN: Datatype identifier for the array base datatype. +
    int rank +
    IN: Rank of the array. +
    const hsize_t dims[/*rank*/] +
    IN: Size of each array dimension. +
    const int perm[/*rank*/] +
    IN: Dimension permutation. +   + (Currently not implemented.)
    Returns: -
    Returns a named datatype identifier if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    + +
    + + + +
    +
    +
    Name: H5Tclose +
    Signature: +
    herr_t H5Tclose(hid_t type_id + ) +
    Purpose: +
    Releases a datatype. +
    Description: +
    H5Tclose releases a datatype. Further access + through the datatype identifier is illegal. Failure to release + a datatype with this call will result in resource leaks. +
    Parameters: +
    +
    hid_t type_id +
    Identifier of datatype to release. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    - -
    -
    -
    Name: H5Tfind -
    Signature: -
    H5T_conv_t H5Tfind(hid_t src_id, - hid_t dst_id, - H5T_cdata_t **pcdata - ) -
    Purpose: -
    Finds a conversion function. -
    Description: -
    H5Tfind finds a conversion function that can - handle a conversion from type src_id to type - dst_id. - The pcdata argument is a pointer to a pointer - to type conversion data which was created and initialized - by the soft type conversion function of this path when the - conversion function was installed on the path. -
    Parameters: -
    -
    hid_t src_id -
    IN: Identifier for the source datatype. -
    hid_t dst_id -
    IN: Identifier for the destination datatype. -
    H5T_cdata_t **pcdata -
    OUT: Pointer to type conversion data. -
    -
    Returns: -
    Returns a pointer to a suitable conversion function if successful. - Otherwise returns NULL. - -
    - -
    @@ -601,93 +611,111 @@ in the HDF5 User's Guide for further information, including a compl
    - +
    -
    Name: H5Tset_overflow +
    Name: H5Tcopy
    Signature: -
    herr_t H5Tset_overflow(H5T_overflow_t func) +
    hid_t H5Tcopy(hid_t type_id)
    Purpose: -
    Sets the overflow handler to a specified function. +
    Copies an existing datatype.
    Description: -
    H5Tset_overflow sets the overflow handler - to be the function specified by func. - func will be called for all datatype conversions that - result in an overflow. +
    H5Tcopy copies an existing datatype. + The returned type is always transient and unlocked.

    - See the definition of H5T_overflow_t in - H5Tpublic.h for documentation - of arguments and return values. - The prototype for H5T_overflow_t is as follows:
    - herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, - void *src_buf, void *dst_buf); - + The type_id argument can be either a datatype + identifier, a predefined datatype (defined in + H5Tpublic.h), or a dataset identifier. + If type_id is a dataset identifier instead of a + datatype identifier, then this function returns a transient, + modifiable datatype which is a copy of the dataset's datatype.

    - The NULL pointer may be passed to remove the overflow handler. + The datatype identifier returned should be released with + H5Tclose or resource leaks will occur. +

    Parameters:
    -
    H5T_overflow_t func -
    Overflow function. +
    hid_t type_id +
    Identifier of datatype to copy. Can be a datatype + identifier, a predefined datatype (defined in + H5Tpublic.h), or a dataset identifier.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    - +
    -
    Name: H5Tget_overflow +
    Name: H5Tcreate
    Signature: - - -H5Tget_overflow () -
    H5T_overflow_t H5Tget_overflow(void) +
    hid_t H5Tcreate(H5T_class_t class, + size_tsize + )
    Purpose: -
    Returns a pointer to the current global overflow function. -
    Description: -
    H5Tset_overflow returns a pointer - to the current global overflow function. - This is an application-defined function that is called whenever a - datatype conversion causes an overflow. -
    Parameters: -
    -
    None. -
    -
    Returns: -
    Returns a pointer to an application-defined function if successful. - Otherwise returns NULL; this can happen if no overflow handling - function is registered. - -
    - - - -
    -
    -
    Name: H5Tcreate -
    Signature: -
    hid_t H5Tcreate(H5T_class_t class, - size_tsize - ) -
    Purpose: -
    Creates a new datatype. +
    Creates a new datatype.
    Description:
    H5Tcreate creates a new datatype of the specified class with the specified number of bytes. @@ -723,74 +751,71 @@ H5Tget_overflow ()
    - +
    -
    Name: H5Tvlen_create +
    Name: H5Tdetect_class
    Signature: -
    hid_t H5Tvlen_create(hid_t base_type_id +
    htri_t H5Tdetect_class(hid_t dtype_id, + H5T_class_tdtype_class )
    Purpose: -
    Creates a new variable-length datatype. +
    Determines whether a datatype contains any datatypes of the + given datatype class.
    Description: -
    H5Tvlen_create creates a new variable-length (VL) datatype. -

    - The base datatype will be the datatype that the sequence is composed of, - characters for character strings, vertex coordinates for polygon lists, etc. - The base type specified for the VL datatype can be of any HDF5 datatype, - including another VL datatype, a compound datatype or an atomic datatype. +

    H5Tdetect_class determines whether the datatype + specified in dtype_id contains any datatypes of the + datatype class specified in dtype_class.

    - When necessary, use H5Tget_super to determine the base type - of the VL datatype. + This function is useful primarily in recursively examining + all the fields and/or base types + of compound, array, and variable-length datatypes.

    - The datatype identifier returned from this function should be - released with H5Tclose or resource leaks will result. + Valid class identifiers are as defined in + H5Tget_class.

    Parameters:
    -
    hid_t base_type_id -
    Base type of datatype to create. +
    hid_t dtype_id +
    Datatype identifier. +
    H5T_class_tdtype_class +
    Datatype class.
    -
    See Also: -
    H5Dget_vlen_buf_size -
    H5Dvlen_reclaim
    Returns: -
    Returns datatype identifier if successful; +
    Returns TRUE or FALSE if successful; otherwise returns a negative value. -
    Non-C API(s): -
    Non-C API(s): +
    -
    - +
    -
    Name: H5Tis_variable_str +
    Name: H5Tenum_create
    Signature: -
    htri_t H5Tis_variable_str(hid_t dtype_id +
    hid_t H5Tenum_create(hid_t parent_id )
    Purpose: -
    Determines whether datatype is a variable-length string. +
    Creates a new enumeration datatype.
    Description: -
    H5Tvlen_create determines whether the datatype - identified in dtype_id is a variable-length string. -

    - This function can be used to distinguish between - fixed and variable-length string datatypes. +

    H5Tenum_create creates a new enumeration datatype + based on the specified base datatype, parent_id, + which must be an integer type.
    Parameters:
    -
    hid_t dtype_id -
    Datatype identifier. +
    hid_t parent_id +
    IN: Datatype identifier for the base datatype.
    Returns: -
    Returns TRUE or FALSE if successful; +
    Returns the datatype identifier for the new enumeration datatype if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tcopy +
    Name: H5Tenum_insert
    Signature: -
    hid_t H5Tcopy(hid_t type_id) +
    herr_t H5Tenum_insert(hid_t type, + const char *name, + void *value + )
    Purpose: -
    Copies an existing datatype. +
    Inserts a new enumeration datatype member.
    Description: -
    H5Tcopy copies an existing datatype. - The returned type is always transient and unlocked. +
    H5Tenum_insert inserts a + new enumeration datatype member into an enumeration datatype.

    - The type_id argument can be either a datatype - identifier, a predefined datatype (defined in - H5Tpublic.h), or a dataset identifier. - If type_id is a dataset identifier instead of a - datatype identifier, then this function returns a transient, - modifiable datatype which is a copy of the dataset's datatype. + type is the enumeration datatype, + name is the name of the new member, and + value points to the value of the new member.

    - The datatype identifier returned should be released with - H5Tclose or resource leaks will occur. - + value points to data which is of the + datatype defined when the enumeration datatype was created.

    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to copy. Can be a datatype - identifier, a predefined datatype (defined in - H5Tpublic.h), or a dataset identifier. +
    hid_t type +
    IN: Datatype identifier for the enumeration datatype. +
    const char *name +
    IN: Name of the new member. +
    void *value +
    IN: Pointer to the value of the new member.
    Returns: -
    Returns a datatype identifier if successful; - otherwise returns a negative value +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tequal +
    Name: H5Tenum_nameof
    Signature: -
    htri_t H5Tequal(hid_t type_id1, - hid_ttype_id2 +
    herr_t H5Tenum_nameof(hid_t type + void *value, + char *name, + size_t size )
    Purpose: -
    Determines whether two datatype identifiers refer to the same datatype. +
    Returns the symbol name corresponding to a specified member of an enumeration datatype.
    Description: -
    H5Tequal determines whether two datatype identifiers - refer to the same datatype. +
    H5Tenum_nameof finds the symbol name that + corresponds to the specified value + of the enumeration datatype type. +

    + At most size characters of the symbol + name are copied into the name buffer. + If the entire symbol name and null terminator + do not fit in the name buffer, then as + many characters as possible are copied + (not null terminated) and the function fails.

    Parameters:
    -
    hid_t type_id1 -
    Identifier of datatype to compare. -
    hid_t type_id2 -
    Identifier of datatype to compare. +
    hid_t type +
    IN: Enumeration datatype identifier. +
    void *value, +
    IN: Value of the enumeration datatype. +
    char *name, +
    OUT: Buffer for output of the symbol name. +
    size_t size +
    IN: Anticipated size of the symbol name, in bytes (characters).
    Returns: -
    When successful, returns a positive value, for TRUE, - if the datatype identifiers refer to the same datatype, - or 0 (zero), for FALSE. - Otherwise returns a negative value. +
    Returns a non-negative value if successful. + Otherwise returns a negative value + and, if size allows it, + the first character of name is + set to NULL.
    Non-C API(s): -
    - +
    -
    Name: H5Tlock +
    Name: H5Tenum_valueof
    Signature: -
    herr_t H5Tlock(hid_t type_id +
    herr_t H5Tenum_valueof(hid_t type + char *name, + void *value )
    Purpose: -
    Locks a datatype. +
    Returns the value corresponding to a specified member of an enumeration datatype.
    Description: -
    H5Tlock locks the datatype specified by the - type_id identifier, making it read-only and - non-destructible. This is normally done by the library for - predefined datatypes so the application does not - inadvertently change or delete a predefined type. - Once a datatype is locked it can never be unlocked. +
    H5Tenum_valueof finds the value that + corresponds to the specified name + of the enumeration datatype type. +

    + The value argument should be at least + as large as the value of H5Tget_size(type) + in order to hold the result.

    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to lock. +
    hid_t type +
    IN: Enumeration datatype identifier. +
    const char *name, +
    IN: Symbol name of the enumeration datatype. +
    void *value, +
    OUT: Buffer for output of the value of the enumeration datatype.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. -
    - +
    -
    Name: H5Tget_class +
    Name: H5Tequal
    Signature: -
    H5T_class_t H5Tget_class(hid_t type_id +
    htri_t H5Tequal(hid_t type_id1, + hid_ttype_id2 )
    Purpose: -
    Returns the datatype class identifier. +
    Determines whether two datatype identifiers refer to the same datatype.
    Description: -
    H5Tget_class returns the datatype class identifier. -

    - Valid class identifiers, as defined in H5Tpublic.h, are: -

    • H5T_INTEGER -
    • H5T_FLOAT -
    • H5T_TIME -
    • H5T_STRING -
    • H5T_BITFIELD -
    • H5T_OPAQUE -
    • H5T_COMPOUND -
    • H5T_REFERENCE -
    • H5T_ENUM -
    • H5T_VLEN -
    • H5T_ARRAY -
    +
    H5Tequal determines whether two datatype identifiers + refer to the same datatype.
    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to query. +
    hid_t type_id1 +
    Identifier of datatype to compare. +
    hid_t type_id2 +
    Identifier of datatype to compare.
    Returns: -
    Returns datatype class identifier if successful; - otherwise H5T_NO_CLASS (-1). +
    When successful, returns a positive value, for TRUE, + if the datatype identifiers refer to the same datatype, + or 0 (zero), for FALSE. + Otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tdetect_class +
    Name: H5Tfind
    Signature: -
    htri_t H5Tdetect_class(hid_t dtype_id, - H5T_class_tdtype_class +
    H5T_conv_t H5Tfind(hid_t src_id, + hid_t dst_id, + H5T_cdata_t **pcdata )
    Purpose: -
    Determines whether a datatype contains any datatypes of the - given datatype class. +
    Finds a conversion function.
    Description: -
    H5Tdetect_class determines whether the datatype - specified in dtype_id contains any datatypes of the - datatype class specified in dtype_class. -

    - This function is useful primarily in recursively examining - all the fields and/or base types - of compound, array, and variable-length datatypes. -

    - Valid class identifiers are as defined in - H5Tget_class. +

    H5Tfind finds a conversion function that can + handle a conversion from type src_id to type + dst_id. + The pcdata argument is a pointer to a pointer + to type conversion data which was created and initialized + by the soft type conversion function of this path when the + conversion function was installed on the path.
    Parameters:
    -
    hid_t dtype_id -
    Datatype identifier. -
    H5T_class_tdtype_class -
    Datatype class. +
    hid_t src_id +
    IN: Identifier for the source datatype. +
    hid_t dst_id +
    IN: Identifier for the destination datatype. +
    H5T_cdata_t **pcdata +
    OUT: Pointer to type conversion data.
    Returns: -
    Returns TRUE or FALSE if successful; - otherwise returns a negative value. - - +
    -
    Name: H5Tget_size +
    Name: H5Tget_array_dims
    Signature: -
    size_t H5Tget_size(hid_t type_id +
    int H5Tget_array_dims( + hid_t adtype_id, + hsize_t *dims[], + int *perm[] )
    Purpose: -
    Returns the size of a datatype. +
    Retrieves sizes of array dimensions and dimension permutations.
    Description: -
    H5Tget_size returns the size of a datatype in bytes. +
    H5Tget_array_dims returns the sizes of the dimensions + and the dimension permutations of the specified array datatype object. +

    + The sizes of the dimensions are returned in the array dims. + The dimension permutations, i.e., C versus FORTRAN array order, + are returned in the array perm.

    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to query. +
    hid_t adtype_id +
    IN: Datatype identifier of array object. +
    hsize_t *dims[] +
    OUT: Sizes of array dimensions. +
    int *perm[] +
    OUT: Dimension permutations.
    Returns: -
    Returns the size of the datatype in bytes if successful; - otherwise 0. +
    Returns the non-negative number of dimensions of the array type if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_size +
    Name: H5Tget_array_ndims
    Signature: -
    herr_t H5Tset_size(hid_t type_id, - size_tsize +
    int H5Tget_array_ndims( + hid_t adtype_id )
    Purpose: -
    Sets the total size for an atomic datatype. +
    Returns the rank of an array datatype.
    Description: -
    H5Tset_size sets the total size in bytes, - size, for a datatype. If the datatype is atomic and size - is decreased so that the significant bits of the datatype 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 datatype still hang over the edge of the new size, then - the number of significant bits is decreased. - The size set for a string should include space for the null-terminator - character, otherwise it will not be stored on (or retrieved from) disk. - Adjusting the size of an string automatically sets the precision - to 8*size. A compound datatype may increase in size, but may not - shrink. All datatypes must have a positive size. +
    H5Tget_array_ndims returns the rank, + the number of dimensions, of an array datatype object.
    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to change size. -
    size_t size -
    Size in bytes to modify datatype. +
    hid_t adtype_id +
    IN: Datatype identifier of array object.
    Returns: -
    Returns a non-negative value if successful; +
    Returns the rank of the array if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_super +
    Name: H5Tget_class
    Signature: -
    hid_t H5Tget_super(hid_t type +
    H5T_class_t H5Tget_class(hid_t type_id )
    Purpose: -
    Returns the base datatype from which a datatype is derived. +
    Returns the datatype class identifier.
    Description: -
    H5Tget_super returns the base datatype from which the - datatype type is derived. -

    - In the case of an enumeration type, the return value is an integer type. +

    H5Tget_class returns the datatype class identifier. +

    + Valid class identifiers, as defined in H5Tpublic.h, are: +

    • H5T_INTEGER +
    • H5T_FLOAT +
    • H5T_TIME +
    • H5T_STRING +
    • H5T_BITFIELD +
    • H5T_OPAQUE +
    • H5T_COMPOUND +
    • H5T_REFERENCE +
    • H5T_ENUM +
    • H5T_VLEN +
    • H5T_ARRAY +
    Parameters:
    -
    hid_t type -
    Datatype identifier for the derived datatype. +
    hid_t type_id +
    Identifier of datatype to query.
    Returns: -
    Returns the datatype identifier for the base datatype if successful; - otherwise returns a negative value. +
    Returns datatype class identifier if successful; + otherwise H5T_NO_CLASS (-1).
    Non-C API(s): -
    - +
    -
    Name: H5Tget_native_type +
    Name: H5Tget_cset
    Signature: -
    hid_t H5Tget_native_type(hid_t type_id, - H5T_direction_t direction +
    H5T_cset_t H5Tget_cset(hid_t type_id )
    Purpose: -
    Returns the native datatype of a specified datatype. +
    Retrieves the character set type of a string datatype.
    Description: -
    H5Tget_native_type returns the equivalent native datatype - for the datatype specified in type_id. -

    - H5Tget_native_type is a high-level function designed - primarily to facilitate use of the H5Dread function, - for which users otherwise must undertake a multi-step process to - determine the native datatype of a dataset prior to reading it - into memory. - It can be used not only to determine - the native datatype for atomic datatypes, - but also to determine the native datatypes of the individual components of - a compound datatype, an enumerated datatype, an array datatype, or - a variable-length datatype. -

    - H5Tget_native_type selects the matching native datatype - from the following list: - 

            H5T_NATIVE_CHAR         
-        H5T_NATIVE_SHORT        
-        H5T_NATIVE_INT          
-        H5T_NATIVE_LONG         
-        H5T_NATIVE_LLONG        
+    
    H5Tget_cset retrieves the character set type 
+        of a string datatype.  Valid character set types are:
+        
       
      
+            
      H5T_CSET_ASCII (0)
+               
      Character set is US ASCII
+        
       
    
+
    Parameters:
+    
    
+        
    hid_t type_id
+            
    Identifier of datatype to query.
+    
    
+
    Returns:
+    
    Returns a valid character set type if successful;
+        otherwise H5T_CSET_ERROR (-1).
+
    Non-C API(s):
+    
    
+        
+
    - H5T_NATIVE_UCHAR - H5T_NATIVE_USHORT - H5T_NATIVE_UINT - H5T_NATIVE_ULONG - H5T_NATIVE_ULLONG - - H5T_NATIVE_FLOAT - H5T_NATIVE_DOUBLE - H5T_NATIVE_LDOUBLE -

    - The direction parameter indicates the order - in which the library searches for a native datatype match. - Valid values for direction are as follows: - - - -
         - H5T_DIR_ASCEND - Searches the above list in ascending size of the datatype,
    - i.e., from top to bottom. (Default) -
      - H5T_DIR_DESCEND   - Searches the above list in descending size of the datatype,
    - i.e., from bottom to top. -
    -

    - H5Tget_native_type is designed primarily for - use with intenger and floating point datatypes. - Time, bifield, opaque, and reference datatypes are returned - as a copy of type_id. -

    - The identifier returned by H5Tget_native_type - should eventually be closed by calling H5Tclose - to release resources. + + +

    +
    +
    Name: H5Tget_ebias +
    Signature: +
    size_t H5Tget_ebias(hid_t type_id + ) +
    Purpose: +
    Retrieves the exponent bias of a floating-point type. +
    Description: +
    H5Tget_ebias retrieves the exponent bias of a floating-point type.
    Parameters:
    hid_t type_id -
    Datatype identifier for the dataset datatype. -
    H5T_direction_t direction -
    Direction of search. +
    Identifier of datatype to query.
    Returns: -
    Returns the native datatype identifier for the - specified dataset datatype if successful; - otherwise returns a negative value. -
    - +
    -
    Name: H5Tget_order +
    Name: H5Tget_fields
    Signature: -
    H5T_order_t H5Tget_order(hid_t type_id +
    herr_t H5Tget_fields(hid_t type_id, + size_t *spos, + size_t *epos, + size_t *esize, + size_t *mpos, + size_t *msize )
    Purpose: -
    Returns the byte order of an atomic datatype. +
    Retrieves floating point datatype bit field information.
    Description: -
    H5Tget_order returns the byte order of an - atomic datatype. -

    - Possible return values are: -

      -
      H5T_ORDER_LE (0) -
      Little endian byte ordering (default). -
      H5T_ORDER_BE (1) -
      Big endian byte ordering. -
      H5T_ORDER_VAX (2) -
      VAX mixed byte ordering (not currently supported). -
    +
    H5Tget_fields retrieves information about the locations of the various + bit fields of a floating point datatype. The field positions are bit + positions in the significant region of the datatype. 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 -
    Identifier of datatype to query. +
    IN: Identifier of datatype to query. +
    size_t *spos +
    OUT: Pointer to location to return floating-point sign bit. +
    size_t *epos +
    OUT: Pointer to location to return exponent bit-position. +
    size_t *esize +
    OUT: Pointer to location to return size of exponent in bits. +
    size_t *mpos +
    OUT: Pointer to location to return mantissa bit-position. +
    size_t *msize +
    OUT: Pointer to location to return size of mantissa in bits.
    Returns: -
    Returns a byte order constant if successful; - otherwise H5T_ORDER_ERROR (-1). +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_order +
    Name: H5Tget_inpad
    Signature: -
    herr_t H5Tset_order(hid_t type_id, - H5T_order_torder +
    H5T_pad_t H5Tget_inpad(hid_t type_id )
    Purpose: -
    Sets the byte ordering of an atomic datatype. +
    Retrieves the internal padding type for unused bits in floating-point datatypes.
    Description: -
    H5Tset_order sets the byte ordering of an atomic datatype. - Byte orderings currently supported are: +
    H5Tget_inpad retrieves the internal padding type for + unused bits in floating-point datatypes. + Valid padding types are:
      -
      H5T_ORDER_LE (0) -
      Little-endian byte ordering (default). -
      H5T_ORDER_BE (1) -
      Big-endian byte ordering. -
      H5T_ORDER_VAX (2) -
      VAX mixed byte ordering (not currently supported). +
      H5T_PAD_ZERO (0) +
      Set background to zeros. +
      H5T_PAD_ONE (1) +
      Set background to ones. +
      H5T_PAD_BACKGROUND (2) +
      Leave background alone.
    Parameters:
    hid_t type_id -
    Identifier of datatype to set. -
    H5T_order_t order -
    Byte ordering constant. +
    Identifier of datatype to query.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a valid padding type if successful; + otherwise H5T_PAD_ERROR (-1).
    Non-C API(s): -
    - +
    -
    Name: H5Tget_precision +
    Name: H5Tget_member_class
    Signature: -
    size_t H5Tget_precision(hid_t type_id +
    H5T_class_t H5Tget_member_class( + hid_t cdtype_id, + int member_no )
    Purpose: -
    Returns the precision of an atomic datatype. +
    Returns datatype class of compound datatype member.
    Description: -
    H5Tget_precision returns the precision of an atomic datatype. The - precision is the number of significant bits which, unless padding is - present, is 8 times larger than the value returned by H5Tget_size(). +
    Given a compound datatype, cdtype_id, the function + H5Tget_member_class returns the datatype class of + the compound datatype member specified by member_no.
    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to query. +
    hid_t cdtype_id +
    IN: Datatype identifier of compound object. +
    int member_no +
    IN: Compound object member number.
    Returns: -
    Returns the number of significant bits if successful; - otherwise 0. +
    Returns the datatype class, a non-negative value, if successful; + otherwise returns a negative value. + - +
    -
    Name: H5Tset_precision +
    Name: H5Tget_member_index
    Signature: -
    herr_t H5Tset_precision(hid_t type_id, - size_tprecision +
    int H5Tget_member_index(hid_t type_id, + const char * field_name )
    Purpose: -
    Sets the precision of an atomic datatype. +
    Retrieves the index of a compound or enumeration datatype member.
    Description: -
    H5Tset_precision sets the precision of an atomic datatype. - 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 datatype. -

    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. +

    H5Tget_member_index retrieves the index of a field + of a compound datatype or an element of an enumeration datatype. +

    + The name of the target field or element is specified in + field_name. +

    + Fields are stored in no particular order + with index values of 0 through N-1, where N is + the value returned by H5Tget_nmembers.

    Parameters:
    hid_t type_id -
    Identifier of datatype to set. -
    size_t precision -
    Number of bits of precision for datatype. +
    Identifier of datatype to query. +
    const char * field_name +
    Name of the field or member whose index is to be retrieved.
    Returns: -
    Returns a non-negative value if successful; +
    Returns a valid field or member index if successful; otherwise returns a negative value. + - +
    -
    Name: H5Tget_offset +
    Name: H5Tget_member_name
    Signature: -
    int H5Tget_offset(hid_t type_id +
    char * H5Tget_member_name(hid_t type_id, + int field_idx )
    Purpose: -
    Retrieves the bit offset of the first significant bit. +
    Retrieves the name of a compound or enumeration datatype member.
    Description: -
    H5Tget_offset retrieves the bit offset of the first significant bit. - The significant 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 laid 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]
    +
    H5Tget_member_name retrieves the name of a field + of a compound datatype or an element of an enumeration datatype. +

    + The index of the target field or element is specified in + field_idx. + Compound datatype fields and enumeration datatype elements + are stored in no particular order + with index values of 0 through N-1, where N + is the value returned by H5Tget_nmembers. +

    + A buffer to receive the name of the field is + allocated with malloc() and the caller is responsible + for freeing the memory used.

    Parameters:
    hid_t type_id
    Identifier of datatype to query. +
    int field_idx +
    Zero-based index of the field or element whose name + is to be retrieved.
    Returns: -
    Returns an offset value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - -
    -
    -
    Name: H5Tset_offset -
    Signature: -
    herr_t H5Tset_offset(hid_t type_id, - size_t offset - ) -
    Purpose: -
    Sets the bit offset of the first significant bit. -
    Description: -
    H5Tset_offset sets the bit offset of the first significant bit. The - significant 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 laid 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 datatype. - -

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

    Parameters: -
    -
    hid_t type_id -
    Identifier of datatype to set. -
    size_t offset -
    Offset of first significant bit. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - -
    -
    -
    Name: H5Tget_pad -
    Signature: -
    herr_t H5Tget_pad(hid_t type_id, - H5T_pad_t * lsb, - H5T_pad_t * msb - ) -
    Purpose: -
    Retrieves the padding type of the least and most-significant bit padding. -
    Description: -
    H5Tget_pad retrieves the padding type of the least and most-significant - bit padding. Valid types are: -
      -
      H5T_PAD_ZERO (0) -
      Set background to zeros. -
      H5T_PAD_ONE (1) -
      Set background to ones. -
      H5T_PAD_BACKGROUND (2) -
      Leave background alone. -
    -
    Parameters: -
    -
    hid_t type_id -
    IN: Identifier of datatype to query. -
    H5T_pad_t * lsb -
    OUT: Pointer to location to return least-significant - bit padding type. -
    H5T_pad_t * msb -
    OUT: Pointer to location to return most-significant - bit padding type. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - -
    -
    -
    Name: H5Tset_pad -
    Signature: -
    herr_t H5Tset_pad(hid_t type_id, - H5T_pad_t lsb, - H5T_pad_t msb - ) -
    Purpose: -
    Sets the least and most-significant bits padding types. -
    Description: -
    H5Tset_pad sets the least and most-significant bits padding types. -
      -
      H5T_PAD_ZERO (0) -
      Set background to zeros. -
      H5T_PAD_ONE (1) -
      Set background to ones. -
      H5T_PAD_BACKGROUND (2) -
      Leave background alone. -
    -
    Parameters: -
    -
    hid_t type_id -
    Identifier 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: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a valid pointer to a string allocated with + malloc() if successful; + otherwise returns NULL.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_sign +
    Name: H5Tget_member_offset
    Signature: -
    H5T_sign_t H5Tget_sign(hid_t type_id +
    size_t H5Tget_member_offset(hid_t type_id, + int memb_no )
    Purpose: -
    Retrieves the sign type for an integer type. +
    Retrieves the offset of a field of a compound datatype.
    Description: -
    H5Tget_sign retrieves the sign type for an integer type. - Valid types are: -
      -
      H5T_SGN_NONE (0) -
      Unsigned integer type. -
      H5T_SGN_2 (1) -
      Two's complement signed integer type. -
    +
    H5Tget_member_offset retrieves the + byte offset of the beginning of a field within a + compound datatype with respect to the beginning + of the compound data type datum.
    Parameters:
    hid_t type_id
    Identifier of datatype to query. +
    int memb_no +
    Number of the field whose offset is requested.
    Returns: -
    Returns a valid sign type if successful; - otherwise H5T_SGN_ERROR (-1). +
    Returns the byte offset of the field if successful; + otherwise returns 0 (zero). + Note that zero is a valid offset and that this function + will fail only if a call to H5Tget_member_class() + fails with the same arguments.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_sign +
    Name: H5Tget_member_type
    Signature: -
    herr_t H5Tset_sign(hid_t type_id, - H5T_sign_t sign +
    hid_t H5Tget_member_type(hid_t type_id, + int field_idx )
    Purpose: -
    Sets the sign property for an integer type. +
    Returns the datatype of the specified member.
    Description: -
    H5Tset_sign sets the sign property for an integer type. -
      -
      H5T_SGN_NONE (0) -
      Unsigned integer type. -
      H5T_SGN_2 (1) -
      Two's complement signed integer type. -
    +
    H5Tget_member_type returns the datatype of the specified member. The caller + should invoke H5Tclose() to release resources associated with the type.
    Parameters:
    hid_t type_id -
    Identifier of datatype to set. -
    H5T_sign_t sign -
    Sign type. +
    Identifier of datatype to query. +
    int field_idx +
    Field index (0-based) of the field type to retrieve.
    Returns: -
    Returns a non-negative value if successful; +
    Returns the identifier of a copy of the datatype of the field + if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_fields +
    Name: H5Tget_member_value
    Signature: -
    herr_t H5Tget_fields(hid_t type_id, - size_t *spos, - size_t *epos, - size_t *esize, - size_t *mpos, - size_t *msize +
    hid_t H5Tget_member_value(hid_t type + int memb_no, + void *value )
    Purpose: -
    Retrieves floating point datatype bit field information. +
    Returns the value of an enumeration datatype member.
    Description: -
    H5Tget_fields retrieves information about the locations of the various - bit fields of a floating point datatype. The field positions are bit - positions in the significant region of the datatype. Bits are - numbered with the least significant bit number zero. - Any (or even all) of the arguments can be null pointers. +
    H5Tget_member_value returns the value of + the enumeration datatype member memb_no. +

    + The member value is returned in a user-supplied buffer + pointed to by value.

    Parameters:
    -
    hid_t type_id -
    IN: Identifier of datatype to query. -
    size_t *spos -
    OUT: Pointer to location to return floating-point sign bit. -
    size_t *epos -
    OUT: Pointer to location to return exponent bit-position. -
    size_t *esize -
    OUT: Pointer to location to return size of exponent in bits. -
    size_t *mpos -
    OUT: Pointer to location to return mantissa bit-position. -
    size_t *msize -
    OUT: Pointer to location to return size of mantissa in bits. +
    hid_t type +
    IN: Datatype identifier for the enumeration datatype. +
    int memb_no, +
    IN: Number of the enumeration datatype member. +
    void *value +
    OUT: Pointer to a buffer for output of the + value of the enumeration datatype member.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_fields +
    Name: H5Tget_native_type
    Signature: -
    herr_t H5Tset_fields(hid_t type_id, - size_t spos, - size_t epos, - size_t esize, - size_t mpos, - size_t msize +
    hid_t H5Tget_native_type(hid_t type_id, + H5T_direction_t direction )
    Purpose: -
    Sets locations and sizes of floating point bit fields. +
    Returns the native datatype of a specified datatype.
    Description: -
    H5Tset_fields sets the locations and sizes of the various - floating-point bit fields. The field positions are bit positions in the - significant region of the datatype. 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 -
    Identifier of datatype to set. -
    size_t spos -
    Sign position, i.e., the bit offset of the floating-point - sign bit. -
    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: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    +
    H5Tget_native_type returns the equivalent native datatype + for the datatype specified in type_id. +

    + H5Tget_native_type is a high-level function designed + primarily to facilitate use of the H5Dread function, + for which users otherwise must undertake a multi-step process to + determine the native datatype of a dataset prior to reading it + into memory. + It can be used not only to determine + the native datatype for atomic datatypes, + but also to determine the native datatypes of the individual components of + a compound datatype, an enumerated datatype, an array datatype, or + a variable-length datatype. +

    + H5Tget_native_type selects the matching native datatype + from the following list: + 

            H5T_NATIVE_CHAR         
+        H5T_NATIVE_SHORT        
+        H5T_NATIVE_INT          
+        H5T_NATIVE_LONG         
+        H5T_NATIVE_LLONG        
 
-
-
-
    
-
    
-
    Name: H5Tget_ebias
-
    Signature:
-    
    size_t H5Tget_ebias(hid_t type_id
-    )
-
    Purpose:
-    
    Retrieves the exponent bias of a floating-point type.
-
    Description:
-    
    H5Tget_ebias retrieves the exponent bias of a floating-point type.
+        H5T_NATIVE_UCHAR
+        H5T_NATIVE_USHORT
+        H5T_NATIVE_UINT
+        H5T_NATIVE_ULONG
+        H5T_NATIVE_ULLONG
+
+        H5T_NATIVE_FLOAT
+        H5T_NATIVE_DOUBLE
+        H5T_NATIVE_LDOUBLE
    +

    + The direction parameter indicates the order + in which the library searches for a native datatype match. + Valid values for direction are as follows: + + + +
         + H5T_DIR_ASCEND + Searches the above list in ascending size of the datatype,
    + i.e., from top to bottom. (Default) +
      + H5T_DIR_DESCEND   + Searches the above list in descending size of the datatype,
    + i.e., from bottom to top. +
    +

    + H5Tget_native_type is designed primarily for + use with intenger and floating point datatypes. + Time, bifield, opaque, and reference datatypes are returned + as a copy of type_id. +

    + The identifier returned by H5Tget_native_type + should eventually be closed by calling H5Tclose + to release resources.

    Parameters:
    hid_t type_id -
    Identifier of datatype to query. +
    Datatype identifier for the dataset datatype. +
    H5T_direction_t direction +
    Direction of search.
    Returns: -
    Returns the bias if successful; - otherwise 0. +
    Returns the native datatype identifier for the + specified dataset datatype if successful; + otherwise returns a negative value. +
    - +
    -
    Name: H5Tset_ebias +
    Name: H5Tget_nmembers
    Signature: -
    herr_t H5Tset_ebias(hid_t type_id, - size_t ebias +
    int H5Tget_nmembers(hid_t type_id )
    Purpose: -
    Sets the exponent bias of a floating-point type. +
    Retrieves the number of elements in a compound or enumeration datatype.
    Description: -
    H5Tset_ebias sets the exponent bias of a floating-point type. +
    H5Tget_nmembers retrieves + the number of fields in a compound datatype or + the number of members of an enumeration datatype.
    Parameters:
    hid_t type_id -
    Identifier of datatype to set. -
    size_t ebias -
    Exponent bias value. +
    Identifier of datatype to query.
    Returns: -
    Returns a non-negative value if successful; +
    Returns the number of elements if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_norm +
    Name: H5Tget_offset
    Signature: -
    herr_t H5Tset_norm(hid_t type_id, - H5T_norm_t norm +
    int H5Tget_offset(hid_t type_id )
    Purpose: -
    Sets the mantissa normalization of a floating-point datatype. +
    Retrieves the bit offset of the first significant bit.
    Description: -
    H5Tset_norm sets the mantissa normalization of - a floating-point datatype. Valid normalization types are: -
      -
      H5T_NORM_IMPLIED (0) -
      MSB of mantissa is not stored, always 1 -
      H5T_NORM_MSBSET (1) -
      MSB of mantissa is always 1 -
      H5T_NORM_NONE (2) -
      Mantissa is not normalized -
    +
    H5Tget_offset retrieves the bit offset of the first significant bit. + The significant 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 laid 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 -
    Identifier of datatype to set. -
    H5T_norm_t norm -
    Mantissa normalization type. +
    Identifier of datatype to query.
    Returns: -
    Returns a non-negative value if successful; +
    Returns an offset value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_inpad +
    Name: H5Tget_order
    Signature: -
    H5T_pad_t H5Tget_inpad(hid_t type_id +
    H5T_order_t H5Tget_order(hid_t type_id )
    Purpose: -
    Retrieves the internal padding type for unused bits in floating-point datatypes. +
    Returns the byte order of an atomic datatype.
    Description: -
    H5Tget_inpad retrieves the internal padding type for - unused bits in floating-point datatypes. - Valid padding types are: -
      -
      H5T_PAD_ZERO (0) -
      Set background to zeros. -
      H5T_PAD_ONE (1) -
      Set background to ones. -
      H5T_PAD_BACKGROUND (2) -
      Leave background alone. -
    +
    H5Tget_order returns the byte order of an + atomic datatype. +

    + Possible return values are: +

      +
      H5T_ORDER_LE (0) +
      Little endian byte ordering (default). +
      H5T_ORDER_BE (1) +
      Big endian byte ordering. +
      H5T_ORDER_VAX (2) +
      VAX mixed byte ordering (not currently supported). +
    Parameters:
    hid_t type_id
    Identifier of datatype to query.
    Returns: -
    Returns a valid padding type if successful; - otherwise H5T_PAD_ERROR (-1). +
    Returns a byte order constant if successful; + otherwise H5T_ORDER_ERROR (-1).
    Non-C API(s): -
    - +
    -
    Name: H5Tset_inpad +
    Name: H5Tget_overflow
    Signature: -
    herr_t H5Tset_inpad(hid_t type_id, - H5T_pad_t inpad - ) + + +H5Tget_overflow () +
    H5T_overflow_t H5Tget_overflow(void)
    Purpose: -
    Fills unused internal floating point bits. +
    Returns a pointer to the current global overflow function.
    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 H5Tset_inpad will be filled - according to the value of the padding value property inpad. - Valid padding types are: -
      -
      H5T_PAD_ZERO (0) -
      Set background to zeros. -
      H5T_PAD_ONE (1) -
      Set background to ones. -
      H5T_PAD_BACKGROUND (2) -
      Leave background alone. -
    +
    H5Tset_overflow returns a pointer + to the current global overflow function. + This is an application-defined function that is called whenever a + datatype conversion causes an overflow.
    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to modify. -
    H5T_pad_t pad -
    Padding type. +
    None.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns a pointer to an application-defined function if successful. + Otherwise returns NULL; this can happen if no overflow handling + function is registered. +
    - +
    -
    Name: H5Tget_cset +
    Name: H5Tget_pad
    Signature: -
    H5T_cset_t H5Tget_cset(hid_t type_id +
    herr_t H5Tget_pad(hid_t type_id, + H5T_pad_t * lsb, + H5T_pad_t * msb )
    Purpose: -
    Retrieves the character set type of a string datatype. +
    Retrieves the padding type of the least and most-significant bit padding.
    Description: -
    H5Tget_cset retrieves the character set type - of a string datatype. Valid character set types are: +
    H5Tget_pad retrieves the padding type of the least and most-significant + bit padding. Valid types are:
      -
      H5T_CSET_ASCII (0) -
      Character set is US ASCII +
      H5T_PAD_ZERO (0) +
      Set background to zeros. +
      H5T_PAD_ONE (1) +
      Set background to ones. +
      H5T_PAD_BACKGROUND (2) +
      Leave background alone.
    Parameters:
    hid_t type_id -
    Identifier of datatype to query. +
    IN: Identifier of datatype to query. +
    H5T_pad_t * lsb +
    OUT: Pointer to location to return least-significant + bit padding type. +
    H5T_pad_t * msb +
    OUT: Pointer to location to return most-significant + bit padding type.
    Returns: -
    Returns a valid character set type if successful; - otherwise H5T_CSET_ERROR (-1). +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_cset +
    Name: H5Tget_precision
    Signature: -
    herr_t H5Tset_cset(hid_t type_id, - H5T_cset_t cset +
    size_t H5Tget_precision(hid_t type_id )
    Purpose: -
    Sets character set to be used. -
    Description: -
    H5Tset_cset the character set to be used. -

    - HDF5 is able to distinguish between character sets of different - nationalities and to convert between them to the extent possible. - Valid character set types are: -

      -
      H5T_CSET_ASCII (0) -
      Character set is US ASCII. -
    +
    Returns the precision of an atomic datatype. +
    Description: +
    H5Tget_precision returns the precision of an atomic datatype. 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 -
    Identifier of datatype to modify. -
    H5T_cset_t cset -
    Character set type. +
    Identifier of datatype to query.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns the number of significant bits if successful; + otherwise 0.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_strpad +
    Name: H5Tget_sign
    Signature: -
    H5T_str_t H5Tget_strpad(hid_t type_id +
    H5T_sign_t H5Tget_sign(hid_t type_id )
    Purpose: -
    Retrieves the storage mechanism for a string datatype. +
    Retrieves the sign type for an integer type.
    Description: -
    H5Tget_strpad retrieves the storage mechanism - for a string datatype, as defined in - H5Tset_strpad. +
    H5Tget_sign retrieves the sign type for an integer type. + Valid types are: +
      +
      H5T_SGN_NONE (0) +
      Unsigned integer type. +
      H5T_SGN_2 (1) +
      Two's complement signed integer type. +
    Parameters:
    hid_t type_id
    Identifier of datatype to query.
    Returns: -
    Returns a valid string storage mechanism if successful; - otherwise H5T_STR_ERROR (-1). +
    Returns a valid sign type if successful; + otherwise H5T_SGN_ERROR (-1).
    Non-C API(s): -
    - +
    -
    Name: H5Tset_strpad +
    Name: H5Tget_size
    Signature: -
    herr_t H5Tset_strpad(hid_t type_id, - H5T_str_t strpad +
    size_t H5Tget_size(hid_t type_id )
    Purpose: -
    Defines the storage mechanism for character strings. +
    Returns the size of a datatype.
    Description: -
    H5Tset_strpad defines the storage mechanism for the string. -

    - 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. -
    - Valid string padding values, as passed in the parameter - strpad, are as follows: -
      -
      H5T_STR_NULLTERM (0) -
      Null terminate (as C does) -
      H5T_STR_NULLPAD (1) -
      Pad with zeros -
      H5T_STR_SPACEPAD (2) -
      Pad with spaces (as FORTRAN does) -
    -

    - When converting from a longer string to a shorter string, - the behavior is as follows. - If the short string is H5T_STR_NULLPAD or - H5T_STR_SPACEPAD, then the string is simply truncated. - If the short string is H5T_STR_NULLTERM, it is - truncated and a null terminator is appended. -

    - When converting from a shorter string to a longer string, - the long string is padded on the end by appending nulls or spaces. - - +

    H5Tget_size returns the size of a datatype in bytes.
    Parameters:
    hid_t type_id -
    Identifier of datatype to modify. -
    H5T_str_t strpad -
    String padding type. +
    Identifier of datatype to query.
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. +
    Returns the size of the datatype in bytes if successful; + otherwise 0.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_nmembers +
    Name: H5Tget_strpad
    Signature: -
    int H5Tget_nmembers(hid_t type_id +
    H5T_str_t H5Tget_strpad(hid_t type_id )
    Purpose: -
    Retrieves the number of elements in a compound or enumeration datatype. +
    Retrieves the storage mechanism for a string datatype.
    Description: -
    H5Tget_nmembers retrieves - the number of fields in a compound datatype or - the number of members of an enumeration datatype. +
    H5Tget_strpad retrieves the storage mechanism + for a string datatype, as defined in + H5Tset_strpad.
    Parameters:
    hid_t type_id
    Identifier of datatype to query.
    Returns: -
    Returns the number of elements if successful; - otherwise returns a negative value. +
    Returns a valid string storage mechanism if successful; + otherwise H5T_STR_ERROR (-1).
    Non-C API(s): -
    - +
    -
    Name: H5Tget_member_class +
    Name: H5Tget_super
    Signature: -
    H5T_class_t H5Tget_member_class( - hid_t cdtype_id, - int member_no +
    hid_t H5Tget_super(hid_t type )
    Purpose: -
    Returns datatype class of compound datatype member. +
    Returns the base datatype from which a datatype is derived.
    Description: -
    Given a compound datatype, cdtype_id, the function - H5Tget_member_class returns the datatype class of - the compound datatype member specified by member_no. +
    H5Tget_super returns the base datatype from which the + datatype type is derived. +

    + In the case of an enumeration type, the return value is an integer type.

    Parameters:
    -
    hid_t cdtype_id -
    IN: Datatype identifier of compound object. -
    int member_no -
    IN: Compound object member number. +
    hid_t type +
    Datatype identifier for the derived datatype.
    Returns: -
    Returns the datatype class, a non-negative value, if successful; +
    Returns the datatype identifier for the base datatype if successful; otherwise returns a negative value. - - +
    -
    Name: H5Tget_member_name +
    Name: H5Tget_tag
    Signature: -
    char * H5Tget_member_name(hid_t type_id, - int field_idx +
    char *H5Tget_tag(hid_t type_id )
    Purpose: -
    Retrieves the name of a compound or enumeration datatype member. +
    Gets the tag associated with an opaque datatype.
    Description: -
    H5Tget_member_name retrieves the name of a field - of a compound datatype or an element of an enumeration datatype. -

    - The index of the target field or element is specified in - field_idx. - Compound datatype fields and enumeration datatype elements - are stored in no particular order - with index values of 0 through N-1, where N - is the value returned by H5Tget_nmembers. -

    - A buffer to receive the name of the field is - allocated with malloc() and the caller is responsible - for freeing the memory used. +

    H5Tget_tag returns the tag associated with + the opaque datatype type_id. +

    + The tag is returned via a pointer to an + allocated string, which the caller must free.

    Parameters:
    hid_t type_id -
    Identifier of datatype to query. -
    int field_idx -
    Zero-based index of the field or element whose name - is to be retrieved. +
    Datatype identifier for the opaque datatype.
    Returns: -
    Returns a valid pointer to a string allocated with - malloc() if successful; - otherwise returns NULL. +
    Returns a pointer to an allocated string if successful; + otherwise returns NULL.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_member_index +
    Name: H5Tinsert
    Signature: -
    int H5Tget_member_index(hid_t type_id, - const char * field_name +
    herr_t H5Tinsert(hid_t type_id, + const char * name, + size_t offset, + hid_t field_id )
    Purpose: -
    Retrieves the index of a compound or enumeration datatype member. +
    Adds a new member to a compound datatype.
    Description: -
    H5Tget_member_index retrieves the index of a field - of a compound datatype or an element of an enumeration datatype. -

    - The name of the target field or element is specified in - field_name. -

    - Fields are stored in no particular order - with index values of 0 through N-1, where N is - the value returned by H5Tget_nmembers. +

    H5Tinsert adds another member to the compound datatype + type_id. The new member has a name which + must be unique within the compound datatype. + The offset argument defines the start of the member + in an instance of the compound datatype, and field_id + is the datatype identifier of the new member. +

    + Note: Members of a compound datatype do not have to be atomic datatypes; + a compound datatype can have a member which is a compound datatype.

    Parameters:
    hid_t type_id -
    Identifier of datatype to query. -
    const char * field_name -
    Name of the field or member whose index is to be retrieved. +
    Identifier of compound datatype to modify. +
    const char * name +
    Name of the field to insert. +
    size_t offset +
    Offset in memory structure of the field to insert. +
    hid_t field_id +
    Datatype identifier of the field to insert.
    Returns: -
    Returns a valid field or member index if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value. - - +
    -
    Name: H5Tget_member_offset +
    Name: H5Tis_variable_str
    Signature: -
    size_t H5Tget_member_offset(hid_t type_id, - int memb_no +
    htri_t H5Tis_variable_str(hid_t dtype_id )
    Purpose: -
    Retrieves the offset of a field of a compound datatype. +
    Determines whether datatype is a variable-length string.
    Description: -
    H5Tget_member_offset retrieves the - byte offset of the beginning of a field within a - compound datatype with respect to the beginning - of the compound data type datum. +
    H5Tvlen_create determines whether the datatype + identified in dtype_id is a variable-length string. +

    + This function can be used to distinguish between + fixed and variable-length string datatypes.

    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to query. -
    int memb_no -
    Number of the field whose offset is requested. +
    hid_t dtype_id +
    Datatype identifier.
    Returns: -
    Returns the byte offset of the field if successful; - otherwise returns 0 (zero). - Note that zero is a valid offset and that this function - will fail only if a call to H5Tget_member_class() - fails with the same arguments. +
    Returns TRUE or FALSE if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_member_type +
    Name: H5Tlock
    Signature: -
    hid_t H5Tget_member_type(hid_t type_id, - int field_idx +
    herr_t H5Tlock(hid_t type_id )
    Purpose: -
    Returns the datatype of the specified member. +
    Locks a datatype.
    Description: -
    H5Tget_member_type returns the datatype of the specified member. The caller - should invoke H5Tclose() to release resources associated with the type. +
    H5Tlock locks the datatype specified by the + type_id identifier, making it read-only and + non-destructible. This is normally done by the library for + predefined datatypes so the application does not + inadvertently change or delete a predefined type. + Once a datatype is locked it can never be unlocked.
    Parameters:
    hid_t type_id -
    Identifier of datatype to query. -
    int field_idx -
    Field index (0-based) of the field type to retrieve. +
    Identifier of datatype to lock.
    Returns: -
    Returns the identifier of a copy of the datatype of the field - if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value. +
    - +
    -
    Name: H5Tinsert +
    Name: H5Topen
    Signature: -
    herr_t H5Tinsert(hid_t type_id, - const char * name, - size_t offset, - hid_t field_id +
    hid_tH5Topen(hid_t loc_id, + const char * name )
    Purpose: -
    Adds a new member to a compound datatype. +
    Opens a named datatype.
    Description: -
    H5Tinsert adds another member to the compound datatype - type_id. The new member has a name which - must be unique within the compound datatype. - The offset argument defines the start of the member - in an instance of the compound datatype, and field_id - is the datatype identifier of the new member. -

    - Note: Members of a compound datatype do not have to be atomic datatypes; - a compound datatype can have a member which is a compound datatype. +

    H5Topen opens a named datatype at the location + specified by loc_id and returns an identifier + for the datatype. loc_id is either a file or + group identifier. The identifier should eventually be closed + by calling H5Tclose to release resources.
    Parameters:
    -
    hid_t type_id -
    Identifier of compound datatype to modify. +
    hid_t loc_id +
    IN: A file or group identifier.
    const char * name -
    Name of the field to insert. -
    size_t offset -
    Offset in memory structure of the field to insert. -
    hid_t field_id -
    Datatype identifier of the field to insert. +
    IN: A datatype name, defined within the file or group identified by loc_id.
    Returns: -
    Returns a non-negative value if successful; +
    Returns a named datatype identifier if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tunregister +
    Name: H5Tset_cset
    Signature: -
    herr_t H5Tunregister(H5T_conv_t func +
    herr_t H5Tset_cset(hid_t type_id, + H5T_cset_t cset )
    Purpose: -
    Removes a conversion function from all conversion paths. +
    Sets character set to be used.
    Description: -
    H5Tunregister removes a conversion function from all conversion paths. -

    - The conversion function pointer type declaration is described in - H5Tregister. +

    H5Tset_cset the character set to be used. +

    + HDF5 is able to distinguish between character sets of different + nationalities and to convert between them to the extent possible. + Valid character set types are: +

      +
      H5T_CSET_ASCII (0) +
      Character set is US ASCII. +
    +
    Parameters: +
    +
    hid_t type_id +
    Identifier of datatype to modify. +
    H5T_cset_t cset +
    Character set type. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Tset_ebias +
    Signature: +
    herr_t H5Tset_ebias(hid_t type_id, + size_t ebias + ) +
    Purpose: +
    Sets the exponent bias of a floating-point type. +
    Description: +
    H5Tset_ebias sets the exponent bias of a floating-point type. +
    Parameters: +
    +
    hid_t type_id +
    Identifier of datatype to set. +
    size_t ebias +
    Exponent bias value. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Tset_fields +
    Signature: +
    herr_t H5Tset_fields(hid_t type_id, + size_t spos, + size_t epos, + size_t esize, + size_t mpos, + size_t msize + ) +
    Purpose: +
    Sets locations and sizes of floating point bit fields. +
    Description: +
    H5Tset_fields sets the locations and sizes of the various + floating-point bit fields. The field positions are bit positions in the + significant region of the datatype. 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 +
    Identifier of datatype to set. +
    size_t spos +
    Sign position, i.e., the bit offset of the floating-point + sign bit. +
    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: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Tset_inpad +
    Signature: +
    herr_t H5Tset_inpad(hid_t type_id, + H5T_pad_t inpad + ) +
    Purpose: +
    Fills unused internal floating point bits. +
    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 H5Tset_inpad will be filled + according to the value of the padding value property inpad. + Valid padding types are: +
      +
      H5T_PAD_ZERO (0) +
      Set background to zeros. +
      H5T_PAD_ONE (1) +
      Set background to ones. +
      H5T_PAD_BACKGROUND (2) +
      Leave background alone. +
    +
    Parameters: +
    +
    hid_t type_id +
    Identifier of datatype to modify. +
    H5T_pad_t pad +
    Padding type. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + + + +
    +
    +
    Name: H5Tset_norm +
    Signature: +
    herr_t H5Tset_norm(hid_t type_id, + H5T_norm_t norm + ) +
    Purpose: +
    Sets the mantissa normalization of a floating-point datatype. +
    Description: +
    H5Tset_norm sets the mantissa normalization of + a floating-point datatype. Valid normalization types are: +
      +
      H5T_NORM_IMPLIED (0) +
      MSB of mantissa is not stored, always 1 +
      H5T_NORM_MSBSET (1) +
      MSB of mantissa is always 1 +
      H5T_NORM_NONE (2) +
      Mantissa is not normalized +
    Parameters:
    -
    H5T_conv_t func -
    Function to remove from conversion paths. +
    hid_t type_id +
    Identifier of datatype to set. +
    H5T_norm_t norm +
    Mantissa normalization type.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value. -
    - +
    -
    Name: H5Tenum_create +
    Name: H5Tset_offset
    Signature: -
    hid_t H5Tenum_create(hid_t parent_id +
    herr_t H5Tset_offset(hid_t type_id, + size_t offset )
    Purpose: -
    Creates a new enumeration datatype. +
    Sets the bit offset of the first significant bit.
    Description: -
    H5Tenum_create creates a new enumeration datatype - based on the specified base datatype, parent_id, - which must be an integer type. +
    H5Tset_offset sets the bit offset of the first significant bit. The + significant 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 laid 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 datatype. + +

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

    Parameters:
    -
    hid_t parent_id -
    IN: Datatype identifier for the base datatype. +
    hid_t type_id +
    Identifier of datatype to set. +
    size_t offset +
    Offset of first significant bit.
    Returns: -
    Returns the datatype identifier for the new enumeration datatype if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tenum_insert +
    Name: H5Tset_order
    Signature: -
    herr_t H5Tenum_insert(hid_t type, - const char *name, - void *value +
    herr_t H5Tset_order(hid_t type_id, + H5T_order_torder )
    Purpose: -
    Inserts a new enumeration datatype member. +
    Sets the byte ordering of an atomic datatype.
    Description: -
    H5Tenum_insert inserts a - new enumeration datatype member into an enumeration datatype. -

    - type is the enumeration datatype, - name is the name of the new member, and - value points to the value of the new member. -

    - name and value must both - be unique within type. -

    - value points to data which is of the - datatype defined when the enumeration datatype was created. +

    H5Tset_order sets the byte ordering of an atomic datatype. + Byte orderings currently supported are: +
      +
      H5T_ORDER_LE (0) +
      Little-endian byte ordering (default). +
      H5T_ORDER_BE (1) +
      Big-endian byte ordering. +
      H5T_ORDER_VAX (2) +
      VAX mixed byte ordering (not currently supported). +
    Parameters:
    -
    hid_t type -
    IN: Datatype identifier for the enumeration datatype. -
    const char *name -
    IN: Name of the new member. -
    void *value -
    IN: Pointer to the value of the new member. +
    hid_t type_id +
    Identifier of datatype to set. +
    H5T_order_t order +
    Byte ordering constant.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tenum_nameof +
    Name: H5Tset_overflow
    Signature: -
    herr_t H5Tenum_nameof(hid_t type - void *value, - char *name, - size_t size - ) +
    herr_t H5Tset_overflow(H5T_overflow_t func)
    Purpose: -
    Returns the symbol name corresponding to a specified member of an enumeration datatype. +
    Sets the overflow handler to a specified function.
    Description: -
    H5Tenum_nameof finds the symbol name that - corresponds to the specified value - of the enumeration datatype type. +
    H5Tset_overflow sets the overflow handler + to be the function specified by func. + func will be called for all datatype conversions that + result in an overflow.

    - At most size characters of the symbol - name are copied into the name buffer. - If the entire symbol name and null terminator - do not fit in the name buffer, then as - many characters as possible are copied - (not null terminated) and the function fails. + See the definition of H5T_overflow_t in + H5Tpublic.h for documentation + of arguments and return values. + The prototype for H5T_overflow_t is as follows:
    + herr_t (*H5T_overflow_t)(hid_t src_id, hid_t dst_id, + void *src_buf, void *dst_buf); + +

    + The NULL pointer may be passed to remove the overflow handler.

    Parameters:
    -
    hid_t type -
    IN: Enumeration datatype identifier. -
    void *value, -
    IN: Value of the enumeration datatype. -
    char *name, -
    OUT: Buffer for output of the symbol name. -
    size_t size -
    IN: Anticipated size of the symbol name, in bytes (characters). +
    H5T_overflow_t func +
    Overflow function.
    Returns: -
    Returns a non-negative value if successful. - Otherwise returns a negative value - and, if size allows it, - the first character of name is - set to NULL. +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    - +
    -
    Name: H5Tenum_valueof +
    Name: H5Tset_pad
    Signature: -
    herr_t H5Tenum_valueof(hid_t type - char *name, - void *value +
    herr_t H5Tset_pad(hid_t type_id, + H5T_pad_t lsb, + H5T_pad_t msb )
    Purpose: -
    Returns the value corresponding to a specified member of an enumeration datatype. +
    Sets the least and most-significant bits padding types.
    Description: -
    H5Tenum_valueof finds the value that - corresponds to the specified name - of the enumeration datatype type. -

    - The value argument should be at least - as large as the value of H5Tget_size(type) - in order to hold the result. +

    H5Tset_pad sets the least and most-significant bits padding types. +
      +
      H5T_PAD_ZERO (0) +
      Set background to zeros. +
      H5T_PAD_ONE (1) +
      Set background to ones. +
      H5T_PAD_BACKGROUND (2) +
      Leave background alone. +
    Parameters:
    -
    hid_t type -
    IN: Enumeration datatype identifier. -
    const char *name, -
    IN: Symbol name of the enumeration datatype. -
    void *value, -
    OUT: Buffer for output of the value of the enumeration datatype. +
    hid_t type_id +
    Identifier 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:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_member_value +
    Name: H5Tset_precision
    Signature: -
    hid_t H5Tget_member_value(hid_t type - int memb_no, - void *value +
    herr_t H5Tset_precision(hid_t type_id, + size_tprecision )
    Purpose: -
    Returns the value of an enumeration datatype member. +
    Sets the precision of an atomic datatype.
    Description: -
    H5Tget_member_value returns the value of - the enumeration datatype member memb_no. -

    - The member value is returned in a user-supplied buffer - pointed to by value. +

    H5Tset_precision sets the precision of an atomic datatype. + 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 datatype. +

    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 -
    IN: Datatype identifier for the enumeration datatype. -
    int memb_no, -
    IN: Number of the enumeration datatype member. -
    void *value -
    OUT: Pointer to a buffer for output of the - value of the enumeration datatype member. +
    hid_t type_id +
    Identifier of datatype to set. +
    size_t precision +
    Number of bits of precision for datatype.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tset_tag +
    Name: H5Tset_sign
    Signature: -
    herr_t H5Tset_tag(hid_t type_id - const char *tag +
    herr_t H5Tset_sign(hid_t type_id, + H5T_sign_t sign )
    Purpose: -
    Tags an opaque datatype. +
    Sets the sign property for an integer type.
    Description: -
    H5Tset_tag tags an opaque datatype type_id - with a descriptive ASCII identifier, tag. +
    H5Tset_sign sets the sign property for an integer type. +
      +
      H5T_SGN_NONE (0) +
      Unsigned integer type. +
      H5T_SGN_2 (1) +
      Two's complement signed integer type. +
    Parameters:
    hid_t type_id -
    IN: Datatype identifier for the opaque datatype to be tagged. -
    const char *tag -
    IN: Descriptive ASCII string with which the - opaque datatype is to be tagged. +
    Identifier of datatype to set. +
    H5T_sign_t sign +
    Sign type.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_tag +
    Name: H5Tset_size
    Signature: -
    char *H5Tget_tag(hid_t type_id +
    herr_t H5Tset_size(hid_t type_id, + size_tsize )
    Purpose: -
    Gets the tag associated with an opaque datatype. +
    Sets the total size for an atomic datatype.
    Description: -
    H5Tget_tag returns the tag associated with - the opaque datatype type_id. -

    - The tag is returned via a pointer to an - allocated string, which the caller must free. +

    H5Tset_size sets the total size in bytes, + size, for a datatype. If the datatype is atomic and size + is decreased so that the significant bits of the datatype 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 datatype still hang over the edge of the new size, then + the number of significant bits is decreased. + The size set for a string should include space for the null-terminator + character, otherwise it will not be stored on (or retrieved from) disk. + Adjusting the size of an string automatically sets the precision + to 8*size. A compound datatype may increase in size, but may not + shrink. All datatypes must have a positive size.
    Parameters:
    hid_t type_id -
    Datatype identifier for the opaque datatype. +
    Identifier of datatype to change size. +
    size_t size +
    Size in bytes to modify datatype.
    Returns: -
    Returns a pointer to an allocated string if successful; - otherwise returns NULL. +
    Returns a non-negative value if successful; + otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tarray_create +
    Name: H5Tset_strpad
    Signature: -
    hid_t H5Tarray_create( - hid_t base, - int rank, - const hsize_t dims[/*rank*/], - const int perm[/*rank*/] +
    herr_t H5Tset_strpad(hid_t type_id, + H5T_str_t strpad )
    Purpose: -
    Creates an array datatype object. +
    Defines the storage mechanism for character strings.
    Description: -
    H5Tarray_create creates a new array datatype object. -

    - base is the datatype of every element of the array, - i.e., of the number at each position in the array. -

    - rank is the number of dimensions and the - size of each dimension is specified in the array dims. - The value of rank is currently limited to - H5S_MAX_RANK and must be greater than 0 - (zero). - All dimension sizes specified in dims must be greater - than 0 (zero). -

    - The array perm is designed to contain the dimension - permutation, i.e. C versus FORTRAN array order. -   - (The parameter perm is currently unused and is not yet implemented.) -

    +

    H5Tset_strpad defines the storage mechanism for the string. +

    + 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. +
    + Valid string padding values, as passed in the parameter + strpad, are as follows: +
      +
      H5T_STR_NULLTERM (0) +
      Null terminate (as C does) +
      H5T_STR_NULLPAD (1) +
      Pad with zeros +
      H5T_STR_SPACEPAD (2) +
      Pad with spaces (as FORTRAN does) +
    +

    + When converting from a longer string to a shorter string, + the behavior is as follows. + If the short string is H5T_STR_NULLPAD or + H5T_STR_SPACEPAD, then the string is simply truncated. + If the short string is H5T_STR_NULLTERM, it is + truncated and a null terminator is appended. +

    + When converting from a shorter string to a longer string, + the long string is padded on the end by appending nulls or spaces. + +

    Parameters:
    -
    hid_t base -
    IN: Datatype identifier for the array base datatype. -
    int rank -
    IN: Rank of the array. -
    const hsize_t dims[/*rank*/] -
    IN: Size of each array dimension. -
    const int perm[/*rank*/] -
    IN: Dimension permutation. -   - (Currently not implemented.) +
    hid_t type_id +
    Identifier of datatype to modify. +
    H5T_str_t strpad +
    String padding type.
    Returns:
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_array_ndims +
    Name: H5Tset_tag
    Signature: -
    int H5Tget_array_ndims( - hid_t adtype_id +
    herr_t H5Tset_tag(hid_t type_id + const char *tag )
    Purpose: -
    Returns the rank of an array datatype. +
    Tags an opaque datatype.
    Description: -
    H5Tget_array_ndims returns the rank, - the number of dimensions, of an array datatype object. +
    H5Tset_tag tags an opaque datatype type_id + with a descriptive ASCII identifier, tag.
    Parameters:
    -
    hid_t adtype_id -
    IN: Datatype identifier of array object. +
    hid_t type_id +
    IN: Datatype identifier for the opaque datatype to be tagged. +
    const char *tag +
    IN: Descriptive ASCII string with which the + opaque datatype is to be tagged.
    Returns: -
    Returns the rank of the array if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value.
    Non-C API(s): -
    - +
    -
    Name: H5Tget_array_dims +
    Name: H5Tunregister
    Signature: -
    int H5Tget_array_dims( - hid_t adtype_id, - hsize_t *dims[], - int *perm[] +
    herr_t H5Tunregister(H5T_conv_t func )
    Purpose: -
    Retrieves sizes of array dimensions and dimension permutations. +
    Removes a conversion function from all conversion paths.
    Description: -
    H5Tget_array_dims returns the sizes of the dimensions - and the dimension permutations of the specified array datatype object. -

    - The sizes of the dimensions are returned in the array dims. - The dimension permutations, i.e., C versus FORTRAN array order, - are returned in the array perm. +

    H5Tunregister removes a conversion function from all conversion paths. +

    + The conversion function pointer type declaration is described in + H5Tregister.

    Parameters:
    -
    hid_t adtype_id -
    IN: Datatype identifier of array object. -
    hsize_t *dims[] -
    OUT: Sizes of array dimensions. -
    int *perm[] -
    OUT: Dimension permutations. +
    H5T_conv_t func +
    Function to remove from conversion paths.
    Returns: -
    Returns the non-negative number of dimensions of the array type if successful; +
    Returns a non-negative value if successful; otherwise returns a negative value. +
    - +
    -
    Name: H5Tclose +
    Name: H5Tvlen_create
    Signature: -
    herr_t H5Tclose(hid_t type_id +
    hid_t H5Tvlen_create(hid_t base_type_id )
    Purpose: -
    Releases a datatype. +
    Creates a new variable-length datatype.
    Description: -
    H5Tclose releases a datatype. Further access - through the datatype identifier is illegal. Failure to release - a datatype with this call will result in resource leaks. +
    H5Tvlen_create creates a new variable-length (VL) datatype. +

    + The base datatype will be the datatype that the sequence is composed of, + characters for character strings, vertex coordinates for polygon lists, etc. + The base type specified for the VL datatype can be of any HDF5 datatype, + including another VL datatype, a compound datatype or an atomic datatype. +

    + When necessary, use H5Tget_super to determine the base type + of the VL datatype. +

    + The datatype identifier returned from this function should be + released with H5Tclose or resource leaks will result.

    Parameters:
    -
    hid_t type_id -
    Identifier of datatype to release. +
    hid_t base_type_id +
    Base type of datatype to create.
    +
    See Also: +
    H5Dget_vlen_buf_size +
    H5Dvlen_reclaim
    Returns: -
    Returns a non-negative value if successful; +
    Returns datatype identifier if successful; otherwise returns a negative value.
    Non-C API(s): -
    -
    @@ -3111,14 +3109,13 @@ And in this document, the
    -
    -
    +
    HDF Help Desk
    Describes HDF5 Release 1.6.0, July 2003
    diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index 27e6491..87fb4e2 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -62,8 +62,7 @@ And in this document, the
    -
    -
    +

    H5Z: Filter and Compression Interface

    @@ -154,6 +153,35 @@ facilitate moving easily between them. + +
    +
    +
    Name: H5Zfilter_avail +
    Signature: +
    herr_t H5Zfilter_avail(H5Z_filter_t filter) +
    Purpose: +
    Determines whether a filter is available. +
    Description: +
    H5Zfilter_avail determines whether the filter + specified in filter is available to the application. +
    Parameters: +
    +
    H5Z_filter_t filter +
    IN: Filter identifier. +
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Non-C API(s): +
    + +
    + +
    @@ -393,41 +421,6 @@ facilitate moving easily between them. -->
    - - -
    -
    -
    Name: H5Zfilter_avail -
    Signature: -
    herr_t H5Zfilter_avail(H5Z_filter_t filter) -
    Purpose: -
    Determines whether a filter is available. -
    Description: -
    H5Zfilter_avail determines whether the filter - specified in filter is available to the application. -
    Parameters: -
    -
    H5Z_filter_t filter -
    IN: Filter identifier. -
    -
    Returns: -
    Returns a non-negative value if successful; - otherwise returns a negative value. -
    Non-C API(s): -
    - -
    - - - - - - -
    @@ -462,14 +455,13 @@ And in this document, the
    -
    -
    +
    HDF Help Desk
    Describes HDF5 Release 1.6.0, July 2003
    -- cgit v0.12