From 49f626b81f028a09d5c287156120a5d405008335 Mon Sep 17 00:00:00 2001 From: Elena Pourmal Date: Wed, 8 Jul 1998 17:28:21 -0500 Subject: [svn-r475] HDF5 Reference Manual files. Main file is RM_H5Front.html. Created from the Alpha1 Ref. Manual, Alpha1 User's Guide Documents and the Alpha2 Source Code. --- doc/src/RM_H5A.html | 506 ++++++++++++++ doc/src/RM_H5D.html | 374 +++++++++++ doc/src/RM_H5E.html | 377 +++++++++++ doc/src/RM_H5F.html | 192 ++++++ doc/src/RM_H5Front.html | 258 ++++++++ doc/src/RM_H5G.html | 882 ++++++++++++++++++++++++ doc/src/RM_H5P.html | 1693 +++++++++++++++++++++++++++++++++++++++++++++++ doc/src/RM_H5S.html | 291 ++++++++ doc/src/RM_H5T.html | 1323 ++++++++++++++++++++++++++++++++++++ doc/src/RM_H5Z.html | 93 +++ 10 files changed, 5989 insertions(+) create mode 100644 doc/src/RM_H5A.html create mode 100644 doc/src/RM_H5D.html create mode 100644 doc/src/RM_H5E.html create mode 100644 doc/src/RM_H5F.html create mode 100644 doc/src/RM_H5Front.html create mode 100644 doc/src/RM_H5G.html create mode 100644 doc/src/RM_H5P.html create mode 100644 doc/src/RM_H5S.html create mode 100644 doc/src/RM_H5T.html create mode 100644 doc/src/RM_H5Z.html diff --git a/doc/src/RM_H5A.html b/doc/src/RM_H5A.html new file mode 100644 index 0000000..a6738e4 --- /dev/null +++ b/doc/src/RM_H5A.html @@ -0,0 +1,506 @@ + + +HDF5/H5A Draft API Specification + + + + +
+

H5A: Attribute Interface

+
+ +

Attribute API Functions

+ +These functions create and manipulate attributes +and information about attributes. + + + +
+ +       + +       + +
+ + +
+
+
Name: H5Acreate +
Signature: +
hid_t H5Acreate(hid_t loc_id, + const char *name, + hid_t datatype, + hid_t dataspace, + hid_t create_plist + ) +
Purpose: +
Creates a dataset as an attribute of another dataset or group. +
Description: +
SC: H5Acreate creates an attribute which is attached to the object + specified with 'location_id'. The name specified with 'name' for each + attribute for an object must be unique for that object. The 'type_id' + and 'space_id' are created with the H5T and H5S interfaces respectively. + Currently only simple dataspaces are allowed for attribute dataspaces. + The 'create_plist_id' property list is currently un-used, but will be + used int the future for optional properties of attributes. The attribute + identifier returned from this function must be released with H5Aclose or resource + leaks will develop. +

+ The link created (see H5G API documentation for more information on + link types) is a hard link, so the attribute may be shared among datasets + and will not be removed from the file until the reference count for the + attribute is reduced to zero. +

+ The location object may be either a group or a dataset, both of + which may have any sort of attribute. +

+ UG: H5Acreate creates an attribute which is attached to the object + specified with loc_id. The name specified with name + for each attribute for an object must be unique for that object. The type_id + and space_id are created with the H5T and H5S interfaces + respectively. Currently only simple dataspaces are allowed for attribute + dataspaces. The create_plist_id property list is currently + unused, but will be used int the future for optional properties of + attributes. The attribute identifier returned from this function must be released + with H5Aclose or resource leaks will develop. Attempting to create an + attribute with the same name as an already existing attribute will fail, + leaving the pre-existing attribute in place. +

+ datatype, dataspace, create_plist in the UG are + type_id, space_id, and create_plist_id, respectively, in the SC +

+

Parameters: +
+
hid_t loc_id +
IN: Object (dataset or group) to be attached to +
const char *name +
IN: Name of attribute to create +
hid_t datatype +
IN: Identifier of datatype for attribute +
hid_t dataspace +
IN: Identifier of dataspace for attribute +
hid_t create_plist +
IN: Identifier of creation property list (currently not used) +
+
Returns: +
Returns an attribute identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aopen_name +
Signature: +
hid_t H5Aopen_name(hid_t loc_id, + const char *name + ) +
Purpose: +
Opens an attribute for an object by looking up the attribute name. +
Description: +
SC: H5Aopen_name opens an existing attribute for access. The attribute + name specified is used to look up the corresponding attribute for the + object. The attribute identifier returned from this function must be released with + H5Aclose or resource leaks will develop. +

+ The location object may be either a group or a dataset, both of + which may have any sort of attribute. +

+ UG: H5Aopen_name opens an attribute which is attached to the object + specified with loc_id. The name specified with name indicates the + attribute to access. The attribute identifier returned from this function must + be released with H5Aclose or resource leaks will develop. +

Parameters: +
+
hid_t loc_id +
IN: Object (dataset or group) to be attached to +
const char *name +
IN: Name of attribute to locate and open +
+
Returns: +
Returns attribute identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aopen_idx +
Signature: +
hid_t H5Aopen_idx(hid_t loc_id, + unsigned int idx + ) +
Purpose: +
Opens the nth attribute for an object. +
Description: +
SC: H5Aopen_idx opens an existing attribute for access. The attribute + index specified is used to look up the corresponding attribute for the + object. The attribute identifier returned from this function must be released with + H5Aclose or resource leaks will develop. +

+ The location object may be either a group or a dataset, both of + which may have any sort of attribute. +

+ UG: H5Aopen_idx opens an attribute which is attached to the object + specified with loc_id. The attribute specified with idx indicates the + idxth attribute to access, starting with '0'. + The attribute identifier returned from this function must be released with + H5Aclose or resource leaks will develop. +

Parameters: +
+
hid_t loc_id +
IN: Object (dataset or group) to be attached to +
unsigned int idx +
IN: Index (0-based) attribute to open +
+
Returns: +
Returns attribute identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Awrite +
Signature: +
herr_t H5Awrite(hid_t attr_id, + hid_t mem_dt, + void *buf + ) +
Purpose: +
Write out data to an attribute. +
Description: +
SC: H5Awrite writes a complete attribute to disk. +

+ UG: H5Awrite writes an attribute, specified with attr_id, + with mem_type_id specifying the datatype in memory. + The entire attribute is written from buf to the file. + This function returns non-negative on success, negative on failure. +

+ mem_dt in SC is mem_type_id in UG. +

+

Parameters: +
+
hid_t attr_id +
IN: Attribute to write +
hid_t mem_dt +
IN: Memory datatype of buffer +
void *buf +
IN: Buffer of data to write +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aread +
Signature: +
herr_t H5Aread(hid_t attr_id, + hid_t mem_dt, + void *buf + ) +
Purpose: +
Read in data from an attribute. +
Description: +
SC: H5Aread reads a complete attribute from disk. +

+ UG: H5Aread reads an attribute, specified with attr_id, + with mem_type_id specifying the datatype in memory. + The entire attribute is read into buf from the file. + This function returns non-negative on success, negative on failure. +

+ mem_dt in SC is mem_type_id in UG. +

+

Parameters: +
+
hid_t attr_id +
IN: Attribute to read +
hid_t mem_dt +
IN: Memory datatype of buffer +
void *buf +
IN: Buffer for data to read +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aget_space +
Signature: +
hid_t H5Aget_space(hid_t attr_id) +
Purpose: +
Gets a copy of the dataspace for an attribute. +
Description: +
H5Aget_space retrieves a copy of the dataspace for an attribute. + The dataspace identifier returned from this function must be released with H5Sclose + or resource leaks will develop. +

+ (Identical desc in UG and SC.) +

+

Parameters: +
+
hid_t attr_id +
IN: Attribute to get dataspace of +
+
Returns: +
Returns dataspace identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aget_type +
Signature: +
hid_t H5Aget_type(hid_t attr_id) +
Purpose: +
Gets a copy of the datatype for an attribute. +
Description: +
H5Aget_type retrieves a copy of the datatype for an attribute. + The datatype identifier returned from this function must be released with + H5Tclose or resource leaks will develop. +

+ (Identical desc in UG and SC.) +

+

Parameters: +
+
hid_t attr_id +
IN: Attribute to get datatype of +
+
Returns: +
Returns a datatype identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aget_name +
Signature: +
size_t H5Aget_name(hid_t attr_id, + char *buf, + size_t buf_size + ) +
Purpose: +
Gets a copy of the name for an attribute. +
Description: +
H5Aget_name retrieves the name of an attribute for an attribute identifier. + Up to 'buf_size' characters are stored in 'buf' followed by a '\0' string + terminator. If the name of the attribute is longer than 'buf_size'-1, + the string terminator is stored in the last position of the buffer to + properly terminate the string. +

+ (Identical desc in UG and SC.) +

+

Parameters: +
+
hid_t attr_id +
IN: Attribute to get name of +
char *buf +
IN: Buffer to store name in +
size_t buf_size +
IN: The size of the buffer to store the string in +
+
Returns: +
Returns the length of the attribute's name, which may be + longer than buf_size, if successful. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Anum_attrs +
Signature: +
int H5Anum_attrs(hid_t loc_id) +
Purpose: +
Determines the number of attributes attached to an object. +
Description: +
H5Anum_attrs returns the number of attributes attached to the dataset or + group, loc_id. +

+ (Identical desc in UG and SC.) +

+

Parameters: +
+
hid_t loc_id +
IN: The object, a dataset or group, to be queried +
+
Returns: +
Returns the number of attributes if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aiterate +
Signature: +
int H5Aiterate(hid_t loc_id, + unsigned * attr_num, + H5A_operator_t op, + void *op_data + ) +
Purpose: +
Calls a user's function for each attribute on an object. +
Description: +
SC: H5Aiterate interates over the attributes of dataset or group + specified with 'loc_id'. For each attribute of the object, the + 'op_data' and some additional information (specified below) are passed + to the 'op' function. The iteration begins with the '*attr_number' + object in the group and the next attribute to be processed by the operator + is returned in '*attr_number'. +

+ The operation receives the identifier for the group or dataset being iterated + over ('loc_id'), the name of the current attribute about the object + ('attr_name') and the pointer to the operator data passed in to H5Aiterate + ('op_data'). The return values from an operator are: +

    +
  • Zero causes the iterator to continue, returning zero when all + attributes have been processed. +
  • Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next attribute. +
  • Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + attribute. +
+
UG: H5Aiterate interates over the attributes of dataset or group + specified with loc_id. For each attribute of the object, + the operator_data and some additional information (specified below) + are passed to the operator function. The iteration begins with + the *attr_number object in the group and the next attribute to be + processed by the operator is returned in *attr_number. +

+ The prototype for H5A_operator_t is:
+ typedef herr_t (*H5A_operator_t)(hid_t loc_id, + const char *attr_name, void *operator_data); +

+ The operation receives the identifier for the group or dataset being iterated over + (loc_id), the name of the current attribute about the object (attr_name) + and the pointer to the operator data passed in to H5Aiterate + (operator_data). The return values from an operator are: +

    +
  • Zero causes the iterator to continue, returning zero when all + attributes have been processed. +
  • Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next attribute. +
  • Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + attribute. +
+
attr_num, op, and op_data in SC are + attr_number, operator, and operator_data, respectively, in UG. +

+

Parameters: +
+
hid_t loc_id +
IN: Object (dataset or group) to be iterated over +
unsigned * attr_num +
IN/OUT: Starting (IN) & Ending (OUT) attribute number +
H5A_operator_t op +
IN: User's function to pass each attribute to +
void *op_data +
IN/OUT: User's data to pass through to iterator operator function +
+
Returns: +
If successful, returns the return value of the last operator + if it was non-zero, or zero if all attributes were processed. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Adelete +
Signature: +
herr_t H5Adelete(hid_t loc_id, + const char *name + ) +
Purpose: +
Deletes an attribute from a location. +
Description: +
SC: H5Adelete removes the named attribute from a dataset or group. + This function should not be used when attribute identifiers are open on 'loc_id' + as it may cause the internal indexes of the attributes to change and future + writes to the open attributes to produce incorrect results. +

+ UG: H5Adelete removes the named attribute from a dataset or group. + This function should not be used when attribute identifiers are open on loc_id as + it may cause the internal indexes of the attributes to change and future + writes to the open attributes to produce incorrect results. + Returns non-negative on success, negative on failure. +

Parameters: +
+
hid_t loc_id +
IN: Object (dataset or group) to have attribute deleted from +
const char *name +
IN: Name of attribute to delete +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Aclose +
Signature: +
herr_t H5Aclose(hid_t attr_id) +
Purpose: +
Close an attribute identifier. +
Description: +
SC: H5Aclose releases an attribute from use. Further use of the + attribute identifier will result in undefined behavior. +

+ UG: H5Aclose releases an attribute from use. + Further use of the attribute identifier will result in undefined behavior. + This function returns non-negative on success, negative on failure. +

Parameters: +
+
hid_t attr_id +
IN: Attribute to release access to +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 6 July 1998 + + + diff --git a/doc/src/RM_H5D.html b/doc/src/RM_H5D.html new file mode 100644 index 0000000..a9f5189 --- /dev/null +++ b/doc/src/RM_H5D.html @@ -0,0 +1,374 @@ + + +HDF5/H5D Draft API Specification + + + + +
+

H5D: Datasets Interface

+
+ +

Dataset Object API Functions

+ +These functions create and manipulate dataset objects, +and set and retrieve their constant or persistent properties. + + + +
+ +       + +       + +
+ + +
+
+
Name: H5Dcreate +
Signature: +
hid_t H5Dcreate(hid_t loc_id, + const char *name, + hid_ttype_id, + hid_tspace_id, + hid_tcreate_plist_id + ) +
Purpose: +
Creates a dataset at the specified location. +
Description: +
H5Dcreate creates a data set with a name, + name, in the file or in the group specified by + the identifier loc_id. + The dataset has the datatype and dataspace identified by + type_id and space_id, respectively. + The specified datatype and dataspace are the datatype and + dataspace of the dataset as it will exist in the file, + which may be different than in application memory. + Dataset creation properties are specified by the argument + create_plist_id. +

+ create_plist_id is a H5P_DATASET_CREATE + property list created with H5Pcreate() and + initialized with the various functions described above. + H5Dcreate() returns a dataset identifier for success + or negative for failure. The identifier should eventually be + closed by calling H5Dclose() to release resources + it uses. +

Parameters: +
+
hid_t loc_id +
Identifier of the file or group to create the dataset within. +
const char * name +
The name of the dataset to create. +
hid_t type_id +
Identifier of the datatype to use when creating the dataset. +
hid_t space_id +
Identifier of the dataspace to use when creating the dataset. +
hid_t create_plist_id +
Identifier of the set creation property list. +
+
Returns: +
Returns a dataset identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Dopen +
Signature: +
hid_t H5Dopen(hid_t loc_id, + const char *name + ) +
Purpose: +
Opens an existing dataset. +
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. +
Parameters: +
+
hid_t loc_id +
Identifier of the file to access the dataset within. +
const char * name +
The name of the dataset to access. +
+
Returns: +
Returns a dataset identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Dget_space +
Signature: +
hid_t H5Dget_space(hid_t dataset_id + ) +
Purpose: +
Returns an identifier for a copy of the dataspace for a dataset. +
Description: +
H5Dget_space returns an identifier for a copy of the + dataspace for a dataset. + The dataspace identifier should be released with the + H5Sclose() function. +
Parameters: +
+
hid_t dataset_id +
Identifier of the dataset to query. +
+
Returns: +
Returns a dataspace identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Dget_type +
Signature: +
hid_t H5Dget_type(hid_t dataset_id + ) +
Purpose: +
Returns an identifier for a copy of the datatype for a dataset. +
Description: +
H5Dget_type returns an identifier for a copy of the + datatype for a dataset. + The datatype should be released with the H5Tclose() function. +

+ If a dataset has a named datatype, then an identifier to the + opened datatype is returned. + Otherwise, the returned datatype is read-only. + If atomization of the datatype fails, then the datatype is closed. +

Parameters: +
+
hid_t dataset_id +
Identifier of the dataset to query. +
+
Returns: +
Returns a datatype identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 +
Identifier of the dataset to query. +
+
Returns: +
Returns a dataset creation property list identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Dread +
Signature: +
herr_t H5Dread(hid_t dataset_id, + hid_t mem_type_id, + hid_t mem_space_id, + hid_t file_space_id, + hid_t xfer_plist_id, + void * buf + ) +
Purpose: +
Reads raw data from the specified dataset into buf, + converting from file datatype and dataspace to + memory datatype and dataspace. +
Description: +
H5Dread reads a (partial) dataset, specified by its + identifier dataset_id, from the file into the + application memory buffer buf. + Data transfer properties are defined by the argument + xfer_plist_id. + The memory datatype of the (partial) dataset is identified by + the identifier mem_type_id. + The part of the dataset to read is defined by + mem_space_id and file_space_id. +

+ file_space_id can be the constant H5S_ALL, + which indicates that the entire file data space is to be referenced. +

+ mem_space_id can be the constant H5S_ALL, + in which case the memory data space is the same as the file data space + defined when the dataset was created. +

+ The number of elements in the memory data space must match + the number of elements in the file data space. +

+ xfer_plist_id can be the constant H5P_DEFAULT, + in which case the default data transfer properties are used. + +

Parameters: +
+
hid_t dataset_id +
Identifier of the dataset read from. +
hid_t mem_type_id +
Identifier of the memory datatype. +
hid_t mem_space_id +
Identifier of the memory dataspace. +
hid_t file_space_id +
Identifier of the dataset's dataspace in the file. +
hid_t xfer_plist_id +
Identifier of a transfer property list for this I/O operation. +
void * buf +
Buffer to store data read from the file. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Dwrite +
Signature: +
herr_t H5Dwrite(hid_t dataset_id, + hid_t mem_type_id, + hid_t mem_space_id, + hid_t file_space_id, + hid_t xfer_plist_id, + const void * buf + ) +
Purpose: +
Writes raw data from an application buffer buf to + the specified dataset, converting from + memory datatype and dataspace to file datatype and dataspace. +
Description: +
H5Dwrite writes a (partial) dataset, specified by its + identifier dataset_id, from the + application memory buffer buf into the file. + Data transfer properties are defined by the argument + xfer_plist_id. + The memory datatype of the (partial) dataset is identified by + the identifier mem_type_id. + The part of the dataset to write is defined by + mem_space_id and file_space_id. +

+ file_space_id can be the constant H5S_ALL. + which indicates that the entire file data space is to be referenced. +

+ mem_space_id can be the constant H5S_ALL, + in which case the memory data space is the same as the file data space + defined when the dataset was created. +

+ The number of elements in the memory data space must match + the number of elements in the file data space. +

+ xfer_plist_id can be the constant H5P_DEFAULT. + in which case the default data transfer properties are used. +

Parameters: +
+
hid_t dataset_id +
Identifier of the dataset read from. +
hid_t mem_type_id +
Identifier of the memory datatype. +
hid_t mem_space_id +
Identifier of the memory dataspace. +
hid_t file_space_id +
Identifier of the dataset's dataspace in the file. +
hid_t xfer_plist_id +
Identifier of a transfer property list for this I/O operation. +
const void * buf +
Buffer with data to be written to the file. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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. +
Parameters: +
+
hid_t dataset_id +
Identifier of the dataset. +
const hsize_t * size +
Array containing the new magnitude of each dimension. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Dclose +
Signature: +
hid_t H5Dclose(hid_t dataset_id + ) +
Purpose: +
+
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 +
Identifier of the dataset to finish access to. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 8 July 1998 + + + diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html new file mode 100644 index 0000000..0065e90 --- /dev/null +++ b/doc/src/RM_H5E.html @@ -0,0 +1,377 @@ + + +HDF5/H5E Draft API Specification + + + + +
+

H5E: Error Interface

+
+ +

Error API Functions

+ +These functions provide error handling capabilities in the HDF5 environment. +

+Provides error handling in the form of a stack. The FUNC_ENTER() macro +clears the error stack whenever an API function is entered. When an error +is detected, an entry is pushed onto the stack. As the functions unwind +additional entries are pushed onto the stack. The API function will return +some indication that an error occurred and the application can print the +error stack. +

+Certain API functions in the H5E package (such as H5Eprint()) +do not clear the error stack. Otherwise, any function which +doesn't have an underscore immediately after the package name +will clear the error stack. For instance, H5Fopen() clears +the error stack while H5F_open() does not. +

+An error stack has a fixed maximum size. If this size is +exceeded then the stack will be truncated and only the +inner-most functions will have entries on the stack. This is +expected to be a rare condition. +

+Each thread has its own error stack, but since +multi-threading has not been added to the library yet, this +package maintains a single error stack. The error stack is +statically allocated to reduce the complexity of handling +errors within the H5E package. + + + +
+ +       + +       + +
+ + +

+
+
Name: H5Eset_auto +
Signature: +
herr_t H5Eset_auto(H5E_auto_t func, + void *client_data + ) +
Purpose: +
Turns automatic error printing on or off. +
Description: +
SC: 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. +

+ The default values before this function is called are + H5Eprint() with client data being the standard error stream, + stderr. +

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

+ UG: If func is not a null pointer, then the function to + which it points will be called automatically when an API + function is about to return an indication of failure. The + function is called with a single argument, the + client_data pointer. 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. +

+ UG signature line reads +
herr_t H5Eset_auto (herr_t(*func)(void*), + void *client_data). +
The UG signature line for H5Eget_auto reads similarly. +

+

Parameters: +
+
H5E_auto_t func +
Function to be called upon an error condition. +
void *client_data +
Data passed to the error function. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Eget_auto +
Signature: +
herr_t H5Eget_auto(H5E_auto_t * func, + void **client_data + ) +
Purpose: +
Returns the current settings for the automatic error stack + traversal function and its data. +
Description: +
SC: H5Eget_auto returns the current settings for the automatic error stack + traversal function and its data. Either (or both) arguments + may be null in which case the value is not returned. +

+ UG: This function returns the current automatic error traversal + settings through the func and client_data + arguments. Either (or both) arguments may be null pointers in + which case the corresponding information is not returned. +

Parameters: +
+
H5E_auto_t * func +
Current setting for the function to be called upon an + error condition. +
void **client_data +
Current setting for the data passed to the error function. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Eclear +
Signature: +
herr_t H5Eclear(void) +
Purpose: +
Clears the error stack for the current thread. +
Description: +
SC: H5Eclear clears the error stack for the current thread. +

+ This function can fail if there are problems initializing the library. +

+ UG: The error stack can be explicitly cleared by calling this + function. The stack is also cleared whenever an API function + is called, with certain exceptions (for instance, + H5Eprint()). +

Parameters: +
+
paramtype param +
xxx +
Should this say "None"? +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Eprint +
Signature: +
herr_t H5Eprint(FILE * stream) +
Purpose: +
Prints the error stack in a default manner. +
Description: +
SC: H5Eprint prints the error stack in some default way. This is just a + convenience function for H5Ewalk() with a function that + prints error messages. Users are encouraged to write there + own more specific error handlers. +

+ UG: The error stack is printed on the specified stream. Even if + the error stack is empty a one-line message will be printed: + HDF5-DIAG: Error detected in thread 0. +

Parameters: +
+
FILE * stream +
xxx +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Ewalk +
Signature: +
herr_t H5Ewalk(H5E_direction_t direction, + H5E_walk_t func, + void * client_data + ) +
Purpose: +
Walks the error stack for the current thread, calling a specified + function. +
Description: +
SC: H5Ewalk walks the error stack for the current thread + and calls the specified function for each error along the way. +

+ direction determines whether the stack is walked + from the inside out or the outside in. + A value of H5E_WALK_UPWARD means begin with the + most specific error and end at the API; + a value of H5E_WALK_DOWNWARD means to start at the + API and end at the inner-most function where the error was first + detected. +

+ func will be called for each error in the error stack. + It's arguments will include an index number (beginning at zero + regardless of stack traversal direction), an error stack entry, + and the client_data pointer passed to + H5E_print. +

+ H5Ewalk can fail if there are problems initializing the library. +

+ UG: The error stack is traversed and func is called for + each member of the stack. Its arguments are an integer + sequence number beginning at zero (regardless of + direction), a pointer to an error description record, + and the client_data pointer. If direction + is H5E_WALK_UPWARD then traversal begins at the + inner-most function that detected the error and concludes with + the API function. The opposite order is + H5E_WALK_DOWNWARD. +

Parameters: +
+
H5E_direction_t direction +
Direction in which the error stack is to be walked. +
H5E_walk_t func +
Function to be called for each error encountered. +
void * client_data +
Data to be passed with func. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Ewalk_cb +
Signature: +
herr_t H5Ewalk_cb(int n, + H5E_error_t *err_desc, + void *client_data + ) +
Purpose: +
Default error stack traversal callback function + that prints error messages to the specified output stream. +
Description: +
H5Ewalk_cb is a default error stack traversal callback function + that prints error messages to the specified output stream. + It is not meant to be called directly but rather as an + argument to the H5Ewalk() function. This function is called + also by H5Eprint(). Application writers are encouraged to + use this function as a model for their own error stack + walking functions. +

+ n is a counter for how many times this function has been + called for this particular traversal of the stack. It always + begins at zero for the first error on the stack (either the + top or bottom error, or even both, depending on the traversal + direction and the size of the stack). +

+ ERR_DESC is an error description. It contains all the + information about a particular error. +

+ CLIENT_DATA is the same pointer that was passed as the + CLIENT_DATA argument of H5Ewalk(). It is expected to be a + file pointer (or stderr if null). +

Parameters: +
+
int n +
Number of times this function has been called + for this traversal of the stack. +
H5E_error_t *err_desc +
Error description. +
void *client_data +
A file pointer, or stderr if null. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Eget_major +
Signature: +
const char * H5Eget_major(H5E_major_t n) +
Purpose: +
Returns a character string describing a major error. +
Description: +
Given a major error number, H5Eget_major returns a constant character string + that describes the error. +
Parameters: +
+
H5E_major_t n +
Major error number. +
+
Returns: +
Returns a pointer to a character string if successful. + Otherwise returns a pointer to "Invalid major error number". +
+ ...or how about... +
+ Returns a pointer to a character string describing the error if successful. + Otherwise returns a pointer to "Invalid major error number". +
+ ...or ... +
+ Returns a character string describing the error if successful. + Otherwise returns "Invalid major error number." +
+ + +
+
+
Name: H5Eget_minor +
Signature: +
const char * H5Eget_minor(H5E_minor_t n) +
Purpose: +
Returns a character string describing a minor error. +
Description: +
Given a minor error number, H5Eget_minor returns a constant character string + that describes the error. +
Parameters: +
+
H5E_minor_t n +
Minor error number. +
+
Returns: +
Returns a pointer to a character string if successful. + Otherwise returns a pointer to "Invalid minor error number". +
+ ...or how about... +
+ Returns a pointer to a character string describing the error if successful. + Otherwise returns a pointer to "Invalid minor error number". +
+ ...or ... +
+ Returns a character string describing the error if successful. + Otherwise returns "Invalid minor error number." +
+ + +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 6 July 1998 + + + diff --git a/doc/src/RM_H5F.html b/doc/src/RM_H5F.html new file mode 100644 index 0000000..912df51 --- /dev/null +++ b/doc/src/RM_H5F.html @@ -0,0 +1,192 @@ + + +HDF5/H5F Draft API Specification + + + + +
+

H5F: File Interface

+
+ +

File API Functions

+ +These functions are designed to provide file-level access to HDF5 files. +Further manipulation of objects inside a file is performed through one of APIs +documented below. + + + +
+ +       + +       + +
+ +
+ +
+
Name: H5Fopen +
Signature: +
hid_t H5Fopen(const char *name, + uintn flags, + hid_t access_template + ) +
Description: +
This is the primary function for opening existing HDF5 files. + The flags parameter determines the file access mode. + There is no read flag, all open files are implicitily opened for + read access. + All flags may be combined with the '|' (boolean OR operator) to + change the behavior of the file open call. + The access_template parameter is a template containing + additional information required for specific methods of access, + parallel I/O for example. The paramters for access templates are + described in the H5P API documentation. +
Parameters: +
+
const char *name +
Name of the file to access. +
uintn flags +
File access flags: +
    +
    H5F_ACC_RDWR +
    Allow read and write access to file. +
+
hid_taccess_template +
Template indicating the file access properties. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + access_template. Use 0 for default access template. +
+
Returns: +
An ID (of type hid_t) for the file upon success, + otherwise negative +
+ +
+
+
Name: H5Fcreate +
Signature: +
hid_t H5Fcreate(const char *name, + uintn flags, + hid_t create_template, + hid_t access_template + ) +
Description: +
This is the primary function for opening and creating HDF5 files. + The flags parameter determines whether an existing + file will be overwritten or not. All newly created files are opened + for both reading and writing. + All flags may be combined with the '|' (boolean OR operator) to + change the behavior of the file open call. + The create_template and access_template + parameters are templates containing additional information required + for specific methods of access or particular aspects of the file + to set when creating a file. + The parameters for creation and access templates are + described in the H5P API documentation. +
Parameters: +
+
const char *name +
Name of the file to access. +
uintn flags +
File access flags: +
    +
    H5F_ACC_TRUNC +
    Truncate file, if it already exists. The file will + be truncated, erasing all data previously stored in + the file. +
+
hid_tcreate_template +
File creation template ID, used when modifying default file meta-data +
hid_taccess_template +
Template indicating the file access properties. + If parallel file access is desired, this is a collective + call according to the communicator stored in the + access_template. Use 0 for default access template. +
+
Returns: +
An ID (of type hid_t) for the file upon success, + otherwise negative +
+ +
+
+
Name: H5Fis_hdf5 +
Signature: +
hbool_t H5Fis_hdf5(const char *name + ) +
Description: +
This function determines whether a file is in the HDF5 format. +
Parameters: +
+
const char *name +
File name to check format. +
+
Returns: +
TRUE/FALSE/negative +
+ +
+
+
Name: H5Fget_create_template +
Signature: +
hid_t H5Fget_create_template(hid_t file_id + ) +
Description: +
This function returns an template ID with a copy of the parameters + used to create this file. Useful for duplicating the parameters + when creating another file. +
Parameters: +
+
hid_t file_id +
File ID to get creation template of +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Fclose +
Signature: +
herr_t H5Fclose(hid_t file_id + ) +
Description: +
This function terminates access to an HDF5 file. If this is the + last file ID open for a file and if access IDs are still in use, + this function will fail. +
Parameters: +
+
hid_t file_id +
File ID to terminate access to. +
+
Returns: +
zero/negative +
+ +
+ +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 29 June 1998 + + + diff --git a/doc/src/RM_H5Front.html b/doc/src/RM_H5Front.html new file mode 100644 index 0000000..374a1ad --- /dev/null +++ b/doc/src/RM_H5Front.html @@ -0,0 +1,258 @@ + + +HDF5 Draft API Specification + + + +
+

HDF5: API Specification
Reference Manual

+
+ +The HDF5 libraries provide several interfaces, each of which provides the +tools required to meet specific aspects of the HDF5 data-handling requirements. + + + +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 29 June 1998 + + + diff --git a/doc/src/RM_H5G.html b/doc/src/RM_H5G.html new file mode 100644 index 0000000..b4baa99 --- /dev/null +++ b/doc/src/RM_H5G.html @@ -0,0 +1,882 @@ + + +HDF5/H5G Draft API Specification + + + + +
+

H5G: Group Interface

+
+ +

Group Object API Functions

+ +The Group interface functions create and manipulate physical groups +of objects on disk. + + + +
+ +       + +       + +
+(NYI = Not yet implemented) +
+ +

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

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

+An object name consists of one or more components separated from +one another by slashes. An absolute name begins with a slash and the +object is located by looking for the first component in the root +object, then looking for the second component in the first object, etc., +until the entire name is traversed. A relative name does not begin +with a slash and the traversal begins with the current working group. + +

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

+
+
Name: H5Gcreate +
Signature: +
hid_t H5Gcreate(hid_t loc_id, + const char *name, + size_t size_hint + ) +
Purpose: +
Creates a new empty group and gives it a name. +
Description: +
H5Gcreate creates a new group with the specified + name at the specified location, loc_id. + The location is identified by a file or group identifier. + The name, name, must not already be taken by some + other object and all parent groups must already exist. +

+ size_hint is a hint for the number of bytes to + reserve to store the names which will be eventually added to + the new group. Passing a value of zero for size_hint + is usually adequate since the library is able to dynamically + resize the name heap, but a correct hint may result in better + performance. + If a non-positive value is supplied for size_hint, + then a default size is chosen. +

+ The return value is a group identifier for the open group. + This group identifier should be closed by calling + H5Gclose() when it is no longer needed. +

Parameters: +
+
hid_t loc_id +
The file or group identifier. +
const char *name +
The absolute or relative name of the new group. +
size_t size_hint +
An optional parameter indicating the number of bytes + to reserve for the names that will appear in the group. + A conservative estimate could result in multiple + system-level I/O requests to read the group name heap; + a liberal estimate could result in a single large + I/O request even when the group has just a few names. + HDF5 stores each name with a null terminator. +
+
Returns: +
Returns a valid group identifier for the open group if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Gopen +
Signature: +
hid_t H5Gopen(hid_t loc_id, + const char *name + ) +
Purpose: +
Opens an existing group for modification and returns a group + identifier for that group. +
Description: +
H5Gopen opens an existing group with the specified name at + the specified location, loc_id. + The location is identified by a file or + group identifier, and returns a group identifier for the group. + The obtained group identifier should be released by calling + H5Gclose() when it is no longer needed. +
Parameters: +
+
hid_t loc_id +
File or group identifier within which group is to be open. +
const char * name +
Name of group to open. +
+
Returns: +
Returns a valid group identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Gset +
Signature: +
herr_t H5Gset (hid_t loc_id, + const char *name + ) +
Purpose: +
Sets the current working group within a file. +
Description: +
H5Gset sets the group with the specified name + to be the current working group for the file which contains it. + This function sets the current working group by modifying the + top element of the current working group stack or, if the + stack is empty, by pushing a new element onto the stack. + The initial current working group is the root group. +

+ loc_id can be a file identifier or a group identifier. +

+ name is an absolute or relative name and is resolved as follows. Each file identifier + has a current working group, initially the root group of the + file. Relative names do not begin with a slash and are relative + to the specified group or to the current working group. + Absolute names begin with a slash and are relative to the file's + root group. For instance, the name /Foo/Bar/Baz is + resolved by first looking up Foo in the root group; + the name Foo/Bar/Baz is resolved by first looking + up the name Foo in the current working group. +

+ Each file identifier maintains its own notion of the current + working group. If loc_id is a group identifier, the + file identifier is derived from the group identifier. +

+ If a single file is opened with multiple calls to H5Fopen(), + which would return multiple file identifiers, then each + identifier's current working group can be set independently + of the other file identifiers for that file. +

Parameters: +
+
hid_t loc_id +
The file or group identifier. +
const char *name +
The name of the new current working group. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Gpush +
Signature: +
herr_t H5Gpush (hid_t loc_id, + const char *name + ) +
Purpose: +
Sets the current working group by pushing a + new element onto the current working group stack. +
Description: +
Each file identifier maintains a stack of groups, the top group + of which is the current working group. The stack initially + contains only the root group. H5Gpush pushes a new group + onto the stack, thus setting a new current working group. +
Parameters: +
+
hid_t loc_id +
File or group identifier. +
const char *name +
The name of the new current working group. The name may be + an absolute or relative name. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Gpop +
Signature: +
herr_t H5Gpop (hid_t loc_id) +
Purpose: +
Removes the top, or latest, entry from the working group stack, + setting the current working group to the previous value. +
Description: +
H5Gpop restores the previous current working group by + popping an element from the current working group stack. + An empty stack implies that the current working group is the root + object. Attempting to pop an empty stack results in failure. +

+ Each file identfier maintains its own notion of the current + working group. That is, if a single file is opened with + multiple calls to H5Fopen(), which returns multiple file + handles, then each identfier's current working group can be + set independently of the other file identfiers for that file. +

+ If loc_id is a group identifier, it is used only to determine the + file identifier for the stack from which to pop the top entry. +

Parameters: +
+
hid_t loc_id +
The file or group identifier. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 +
Group identifier to release. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 name 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 +
File or group identifier. +
H5G_link_t link_type +
Link type. + Possible values are H5G_LINK_HARD and H5G_LINK_SOFT. +
const char * current_name +
Name of the existing object if link is a hard link. + Can be anything for the soft link. +
const char * new_name +
New name for the object. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Gunlink +      + (Not implemented in this release.) +
Signature: +
herr_t H5Gunlink(hid_t loc_id, + const char *name + ) +
Purpose: +
Removes the specified name from the group graph and + decrements the link count for the object to which name points +
Description: +
H5Gunlink removes an association between a name and an object. + Object headers keep track of how many hard links refer to the object; + when the hard 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 reclaimed. If the object is open, the + reclamation of the file space is delayed until all handles to the + object are closed. +

Parameters: +
+
hid_t loc_id +
Identifier of the file containing the object. +
const char * name +
Name of the object to unlink. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Giterate +
Signature: +
int H5Giterate(hid_t loc_id, + const char *name, + int *idx, + H5G_operator_t operator, + void *operator_data + ) +
Purpose: +
Iterates an operation over the entries of a group. +
Description: +
H5Giterate iterates over the members of + name in the file or group specified with + loc_id. + For each object in the group, the operator_data + and some additional information, specified below, are + passed to the operator function. + The iteration begins with the idx object in the + group and the next element to be processed by the operator is + returned in idx. If idx + is NULL, then the iterator starts at the first group member; + 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 H5G_operator_t is: +

    +
    typedef herr_t *(H5G_operator_t)(hid_t group_id, + const char *member_name, void *operator_data/*in,out*/); +
+
The operation receives the group identifier for the group being + iterated over, group_id, the name of the current + object within the group, member_name, and the + pointer to the operator data passed in to H5Giterate, + operator_data. +

+ The return values from an operator are: +

    +
  • Zero causes the iterator to continue, returning + zero when all group members have been processed. +
  • Positive causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can be + restarted at the next group member. +
  • Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + group member. +
+
Parameters: +
+
hid_t loc_id +
IN: File or group identifier. +
const char *name +
IN: Group over which the iteration is performed. +
int *idx +
IN/OUT: Location at which to begin the iteration. +
H5G_iterate_t operator +
IN: Operation to be performed on an object at each step of + the iteration. +
void *operator_data +
IN/OUT: Data associated with the operation. +
+
Returns: +
Returns the return value of the last operator if it was non-zero, + or zero if all group members were processed. + Otherwise, returns FAIL (-1). +
+ + +
+
+
Name: H5Gmove +      + (Not implemented in this release.) +
Signature: +
herr_t H5Gmove(hid_t loc_id, + const char *src, + const char *dst + ) +
Purpose: +
Renames an object within an HDF5 file. +
Description: +
H5Gmove renames an object within an HDF5 file. + The original name, src, is unlinked from the + group graph and the new name, dst, is inserted + as an atomic operation. Both names are interpreted relative + to loc_id, which is either a file or a group + identifier. +
Parameters: +
+
hid_t loc_id +
File or group identifier. +
const char *src +
Object's original name. +
const char *dst +
Object's new name. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Gstat +
Signature: +
herr_t H5Gstat(hid_t loc_id, + const char *name, + hbool_t follow_link, + H5G_stat_t *statbuf + ) +
Purpose: +
Returns information about an object. +
Description: +
H5Gstat returns information about the + specified object through the statbuf argument. + loc_id (a file, group, or dataset 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. +

+ H5Gstat() fills in the following data structure: + 

+                  typedef struct H5G_stat_t {
+                      unsigned long fileno[2];
+                      unsigned long objno[2];
+                      unsigned nlink;
+                      H5G_type_t type;
+                      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). + 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, + or H5G_LINK. + 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. +
Parameters: +
+
hid_t loc_id +
IN: File, group, or dataset 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 SUCCEED (0) with the fields of STATBUF (if non-null) initialized. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Gget_linkval +
Signature: +
herr_t H5Gget_linkval(hid_t loc_id, + const char *name, + size_t size, + char *value + ) +
Purpose: +
Returns link value. +
Description: +
H5Gget_linkval returns size + characters of the link value through the value + argument if loc_id (a file or group identifier) + and name specify a symbolic link. + If size is smaller than the link value, then + value will not be null terminated. +

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

+ Use H5Gstat() to get the size of a link value. +

Parameters: +
+
hid_t loc_id +
IN: Identifier of the file or group . +
const char *name +
IN: Name of the object whose link value is to be checked. +
size_t size +
IN: Maximum number of characters of value + to be returned. +
char *value +
OUT: Link value. +
+
Returns: +
Returns SUCCEED (0), with the link value in value, + if successful. + Otherwise returns FAIL (-1). +
+ + +
+
+UNUSED PORTIONS OF EMAIL NOTES. +
+.... in left margin indicates where material was pulled out for use. +
+
+
+
+Hi Elena, here's a hodgepodge of stuff from html documents and
+previous e-mails to answer your questions. Let me know if you need
+further clarification.
+
+....
+....  [H5Gmove and H5Gunlink "NYI" comments were here]
+....
+
+Elena> We need little bit more user-friendly description of the H5Gstat and
+Elena> H5Giterate functions.
+
+>From a Mar 31 e-mail...
+
+Robb>
+....
+....  [H5Giterate was here]
+....
+Robb> 
+Robb> 
+Robb> Group Information Functions:
+....
+....  [H5Gstat was here]
+....
+Robb> 
+Robb> herr_t H5Gname(hid_t group_id, char *name, size_t max_name_len);
+Robb>
+Robb> This function retrieves the name of the group for a group ID.  The
+Robb> name is returned in 'name' up to the length specified in 'max_name_len'.
+Robb>
+....
+....  [H5Gget_linkval was here]
+....
+Robb> 
+Robb> H5Giterate example #1: The operator just looks at the member name and if it has an
+Robb>     `X' in it then it returns 1, otherwise return zero.  Returning 1 (or any
+Robb>     positive value) causes the iterator to immediately return that value.  If
+Robb>     none of the operators return 1 then the iterator eventually returns zero.
+Robb> 
+Robb> 1  herr_t
+Robb> 2  any_X (hid_t group_id/*unused*/,
+Robb> 4         const char *member_name,
+Robb> 5         void *op_data/*unused*/)
+Robb> 6  {
+Robb> 7      return strchr(member_name,'X') ? 1 : 0;
+Robb> 8  }
+Robb> 
+Robb> The iterator is invoked as:
+Robb> 
+Robb> 9  int elmt=0;
+Robb> 10  herr_t found = H5Giterate(file_id, "/foo", &elmt, any_X, NULL);
+Robb> 11  
+Robb> 12  if (found<0) {
+Robb> 13     printf ("Error iterating through group, at member %d\n", elmt);
+Robb> 14  } else if (found) {
+Robb> 15     printf ("Yes, member %d has an `X' in the name\n", elmt);
+Robb> 16  } else {
+Robb> 17     printf ("No member name contains an `X'\n");
+Robb> 18  }
+Robb> 
+Robb> H5Giterate example #2: An iterator to find an object whose name contains an `X'
+Robb>     This is the same as Example 1 except the operator also returns the name
+Robb>     that contains the `X'.  We do this by passing a pointer to a `char*' as the
+Robb>     operator data and the operator will initialize that `char*' by strdup'ing
+Robb>     the object name.
+Robb> 
+Robb> 1  herr_t
+Robb> 2  find_X (hid_t group_id/*unused*/,
+Robb> 4          const char *member_name,
+Robb> 5          void *op_data/*out*/)
+Robb> 6  {
+Robb> 7      if (strchr(member_name,'X')) {
+Robb> 8          *((char**)op_data) = strdup(member_name);
+Robb> 9          return 1;
+Robb> 10      }
+Robb> 11      return 0;
+Robb> 12  }
+Robb> 
+Robb> To print all the names with an `X' the iterator is invoked
+Robb> repeatedly until it returns zero.
+Robb> 
+Robb> 13  int elmt = 0;
+Robb> 14  char *name;
+Robb> 15  while (H5Giterate(file_id, "/foo", &elmt, find_X, &name)) {
+Robb> 16      puts (name);
+Robb> 17      free (name);
+Robb> 18  }
+Robb> 
+Robb> H5Giterate example #3: Print all names that contain the specified character.
+Robb>     This is the same as Example 2 except we have to pass data into the operator
+Robb>     as well as get data out.  We create a struct that contains the input data
+Robb>     (character to look for) and a slot for the output data (the name) and pass
+Robb>     that as the operator data.
+Robb> 
+Robb> 1  typedef struct {
+Robb> 2      char look_for;
+Robb> 3      char *name;
+Robb> 4  } find_char_t;
+Robb> 5  
+Robb> 6  herr_t
+Robb> 7  find_char (hid_t group_id/*unused*/,
+Robb> 9             const char *member_name,
+Robb> 10             find_char_t *op_data/*in,out*/)
+Robb> 11  {
+Robb> 13      if (strchr(member_name, op_data->look_for)) {
+Robb> 14          op_data->name = strdup (member_name);
+Robb> 15          return 1;
+Robb> 16      }
+Robb> 17      return 0;
+Robb> 18  }
+Robb> 
+Robb> To print all names that have a `Y' one would say
+Robb> 
+Robb> 19  find_char_t op_data;
+Robb> 20  int elmt = 0;
+Robb> 21  op_data->look_for = 'Y';
+Robb> 22  while (H5Giterate(file_id, "/foo", &elmt, find_X, &op_data)) {
+Robb> 23      puts (op_data->name);
+Robb> 24      free (op_data->name);
+Robb> 25  }
+Robb> 
+Robb> H5Giterate example #4: Efficient version of Example 3.
+Robb>     Examples 2 and 3 weren't too efficient because we kept interrupting the
+Robb> iterator and it had to start over, albeit from the middle of the search. If
+Robb> we could allow the iterator to go further then we wouldn't end up scanning
+Robb> through the leaf nodes of the symbol table so often (searching for a
+Robb> particular index, n, in a B-tree is an O(n) operation).
+Robb>     The H5Glist() function defined earlier returns the names of all the group
+Robb> members which belong to a certain class, H5G_ALL, H5G_DATASET, or H5G_GROUP.
+Robb> This example shows how to implement that functionality.
+Robb>     First we need a struct to describe the operator data and it's return
+Robb> value(s).  These correspond to the arguments presented for H5Glist, whose
+Robb> definition is at the end of this example. (Since most of the work is done by
+Robb> the operator we have to pass all this stuff back and forth through the
+Robb> iterator).
+Robb> 
+Robb> 1  typedef struct {
+Robb> 2      size_t     name_heap_size;
+Robb> 3      char       *name_heap;
+Robb> 4      unsigned   max_entries;
+Robb> 5      char       *names[];
+Robb> 6      int        type;
+Robb> 7      unsigned   cur_entries; /* How many names read so far */
+Robb> 8      size_t     cur_heap_size; /* How large is the heap */
+Robb> 9  } H5G_list_t;
+Robb> 
+Robb> The operator checks if an object is the right type, and if so adds it to
+Robb> the return value arrays in the op_data struct.  If the arrays become full
+Robb> then the operator returns 1 to stop the iterator. The H5*isa() functions
+Robb> return true iff the named object is of the * type (sans error handling).
+Robb> 
+Robb> 10  herr_t
+Robb> 11  H5G_list_op (hid_t grp_id, const char *memb_name,
+Robb> 12               H5G_list_t *op_data)
+Robb> 13  {
+Robb> 14      char *out_name;
+Robb> 15  
+Robb> 16      if (H5G_ALL==op_data->type ||
+Robb> 17          (H5G_DATASET==op_data->type && H5Disa(grp_id,memb_name)) ||
+Robb> 18          (H5G_GROUP==op_data->type && H5Gisa(grp_id, memb_name))) {
+Robb> 19  
+Robb> 20          /* Is there enough room for the name in the heap? */
+Robb> 21          if (op_data->cur_heap_size + strlen(memb_name) + 1 >
+Robb> 22              op_data->name_heap_size) {
+Robb> 23              return 2; /*try again later, see lines 59-62*/
+Robb> 24          }
+Robb> 25  
+Robb> 26          /* Add name to op_data return value arrays */
+Robb> 27          out_name = op_data->name_heap + op_data->cur_heap_size;
+Robb> 28          strcpy (out_name, memb_name);
+Robb> 29          op_data->names[op_data->cur_entries] = out_name;
+Robb> 30          op_data->cur_heap_size += strlen(memb_name) + 1;
+Robb> 31  
+Robb> 32          /* Is the output full? */
+Robb> 33          if (op_data->cur_entries >= op_data->max_entries) {
+Robb> 34              return 1;
+Robb> 35          }
+Robb> 36      }           
+Robb> 37      return 0;
+Robb> 38  }
+Robb> 
+Robb> And finally, the definition of H5Glist():
+Robb> 
+Robb> 39  int
+Robb> 40  H5Glist (hid_t group_id, size_t name_heap_size, char *name_heap,
+Robb> 41           int *start_idx, unsigned max_entries, char *names[],
+Robb> 42           int type)
+Robb> 43  {
+Robb> 44      H5G_list_t op_data;
+Robb> 45      herr_t status;
+Robb> 46  
+Robb> 47      op_data->name_heap_size = name_heap_size;
+Robb> 48      op_data->name_heap = name_heap;
+Robb> 49      op_data->max_entries = max_entries;
+Robb> 50      op_data->names = names;
+Robb> 51      op_data->type = type;
+Robb> 52      op_data->cur_entries = 0;
+Robb> 53      op_data->cur_heap_size = 0;
+Robb> 54  
+Robb> 55      if (0==cur_entries) return 0;
+Robb> 56      status = H5Giterate (group_id, ".", start_idx, H5G_list_op,
+Robb> 57                           &op_data);
+Robb> 58  
+Robb> 59      if (2==status && 0==op_data->cur_entries) {
+Robb> 60          return -1; /*heap not large enough for even one name*/
+Robb> 61      } else if (2==status) {
+Robb> 62          --*start_idx; /*heap overflow, try again later*/
+Robb> 63      } else if (status<0) {
+Robb> 64          return status; /*iterator or operator error*/
+Robb> 65      }
+Robb> 66      return op_data->cur_entries;
+Robb> 67  }
+Robb> 
+Robb>     The only other really interesting thing in this example are lines 23, 61,
+Robb> and 62.  We don't know if the name heap will overflow until we find a name to
+Robb> put there.  And then if it does, we need to be able to restart the iterator at
+Robb> the entry that failed instead of the following entry.
+Robb> 
+Robb> H5Giterate example #5: Print all the names of objects in a group, without any
+Robb>                         buffers.
+Robb> ---------------------
+Robb> 
+Robb> herr_t print_names (hid_t grp_id, const char *name, void *opdata)
+Robb> {
+Robb>     puts (name);
+Robb>     return 0;
+Robb> }
+Robb> 
+Robb> {
+Robb>     H5Giterate (file_id, "/foo/bar", NULL, print_names, NULL);
+Robb> }
+
+Elena> I believe there is a typo in the H5Pget_layout function in the source
+Elena> code. Second argument ( H5D_layout_t *layout is missing....)  
+
+It's returned by value, not reference.  It returns only the class of
+layout and then, based on the class, you must call some other H5Pget
+function like H5Pget_chunk() like this:
+
+	hid_t dcpl; /*dataset creation property list*/
+	hsize_t dims[32]; /*chunk dimensions*/
+	...
+	switch (H5Pget_layout(dcpl)) {
+	case H5D_CHUNKED:
+	    H5Pget_chunk(dcpl, NELMTS(dims), dims);
+	    break;
+	...
+	case H5D_LAYOUT_ERROR:
+	    ...
+	...
+	}
+
+
+Quincy and html> 
+Quincy and html> 
+....
+....  [Datatype material move to H5T.html]
+....
+Quincy and html> 
+Quincy and html> 
+
+
+
+
+
+ +
+
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 8 July 1998 + + + diff --git a/doc/src/RM_H5P.html b/doc/src/RM_H5P.html new file mode 100644 index 0000000..90d6920 --- /dev/null +++ b/doc/src/RM_H5P.html @@ -0,0 +1,1693 @@ + + +HDF5/H5P Draft API Specification + + + + +
+

H5P: Property List Interface

+
+ +

Property List API Functions

+ +These functions manipulate property list objects to allow objects which require +many different parameters to be easily manipulated. + + + + + + + +
+ + General Property List Operations + + +

File Creation Properties +

+ +		       + + File Access Properties + + +       + + Dataset Creation Properties + + +

Dataset Memory and Transfer Properties +

+ +
+
+||   Available only in the parallel HDF5 library. +
+ +
+
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 H5F + for details about the file creation properties. +
H5P_FILE_ACCESS +
Properties for file access. + See H5F + for details about the file creation properties. +
H5P_DATASET_CREATE +
Properties for dataset creation. + See H5D + for details about dataset creation properties. +
H5P_DATASET_XFER +
Properties for raw data transfer. + See H5D + for details about raw data transfer properties. +
+
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). +
+ + +
+
+
Name: H5Pclose +
Signature: +
herr_t H5Pclose(hid_t plist + ) +
Purpose: +
Terminates access to a property list. +
Description: +
H5Pclose terminates access to a property list. + All property lists should be closed when the application is + finished accessing them. + This frees resources used by the property list. +
Parameters: +
+
hid_t plist +
IN: Identifier of the property list to terminate access to. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 identied 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). +
+ + +
+
+
Name: H5Pcopy +
Signature: +
hid_t H5Pcopy(hid_t plist + ) +
Purpose: +
Copies an existing property list to create a new property list. +
Description: +
H5Pcopy copies an existing property list to create + a new property list. + The new property list has the same properties and values + as the original property list. +
Parameters: +
+
hid_t plist +
IN: Identifier of property list to duplicate. +
+
Returns: +
Returns a property list identifier if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_version +
Signature: +
herr_t H5Pget_version(hid_t plist, + int * boot, + int * freelist, + int * stab, + int * shhdr + ) +
Purpose: +
Retrieves the version information of various objects for + a file creation property list. +
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. +
Parameters: +
+
hid_t plist +
IN: Identifier of the file creation property list. +
int * boot +
OUT: Pointer to location to return boot 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_userblock +
Signature: +
herr_t H5Pset_userblock(hid_t plist, + hsize_t size + ) +
Purpose: +
Sets user block size. +
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.). +
Parameters: +
+
hid_t plist +
IN: Identifier of property list to modify. +
hsize_t size +
IN: Size of the user-block in bytes. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_userblock +
Signature: +
herr_t H5Pget_userblock(hid_t plist, + hsize_t * size + ) +
Purpose: +
Retrieves the size of a user block. +
Description: +
H5Pget_userblock retrieves the size of a user block + in a file creation property list. +
Parameters: +
+
hid_t plist +
IN: Identifier for property list to query. +
hsize_t * size +
OUT: Pointer to location to return user-block size. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_sizes +
Signature: +
herr_t H5Pset_sizes(hid_t plist, + size_t sizeof_addr, + size_t sizeof_size + ) +
Purpose: +
Sets the byte size of the offsets and lengths used to address objects + in an HDF5 file. +
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 4 bytes. Valid values currenly are 2, 4, 8 and + 16. +
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. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 +
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 SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_mpi +
Signature: +
herr_t H5Pset_mpi(hid_t plist, + MPI_Comm comm, + MPI_Info info + ) +
Purpose: +
Retrieves the access mode for parallel I/O and the user supplied + communicator and info object. +
Description: +
H5Pset_mpi stores the access mode for MPIO call and the user supplied + communicator and info in the access property list, which can then + be used to open file. This function is available only in the + parallel HDF5 library and is not a collective function. +
Parameters: +
+
hid_t plist +
IN: Identifier of property list to modify +
MPI_Comm comm +
IN: MPI communicator to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated comm. Any modification to comm after + this function call returns may have undetermined effect + to the access property list. Users should call this function + again to setup the property list. +
MPI_Info info +
IN: MPI info object to be used for file open as defined in + MPI_FILE_OPEN of MPI-2. This function does not make a + duplicated info. Any modification to info after + this function call returns may have undetermined effect + to the access property list. Users should call this function + again to setup the property list. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_mpi +
Signature: +
herr_t H5Pget_mpi(hid_t plist, + MPI_Comm *comm, + MPI_Info *info + ) +
Purpose: +
Retrieves the communicator and info object. +
Description: +
H5Pget_mpi retrieves the communicator and info object + that have been set by H5Pset_mpi. + This function is available only in the parallel HDF5 library + and is not a collective function. +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list that has been set + successfully by H5Pset_mpi. +
MPI_Comm * comm +
OUT: Pointer to location to return the communicator. +
MPI_Info * info +
OUT: Pointer to location to return the info object. +
+
Returns: +
Returns SUCCEED (0) if the file access property list is set to the MPI. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Pset_xfer +
Signature: +
herr_t H5Pset_xfer(hid_t plist, + H5D_transfer_t data_xfer_mode + ) +
Purpose: +
Sets the transfer mode of the dataset transfer property list. +
Description: +
H5Pset_xfer sets the transfer mode of the dataset transfer property list. + The list can then be used to control the I/O transfer mode + during dataset accesses. This function is available only + in the parallel HDF5 library and is not a collective function. +

+ Valid data transfer modes are: +

    +
    H5D_XFER_INDEPENDENT +
    Use independent I/O access. + (Currently the default mode.) +
    H5D_XFER_COLLECTIVE +
    Use MPI collective I/O access. +
    H5D_XFER_DFLT +
    User default I/O access. +
+
Parameters: +
+
hid_t plist +
IN: Identifier of a dataset transfer property list +
H5D_transfer_t data_xfer_mode +
IN: Data transfer mode. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_xfer +
Signature: +
herr_t H5Pget_xfer(hid_t plist, + H5D_transfer_t * data_xfer_mode + ) +
Purpose: +
Retrieves the transfer mode from the dataset transfer property list. +
Description: +
H5Pget_xfer retrieves the transfer mode from the dataset + transfer property list. + This function is available only in the parallel HDF5 library + and is not a collective function. +
Parameters: +
+
hid_t plist +
IN: Identifier of a dataset transfer property list. +
H5D_transfer_t * data_xfer_mode +
OUT: Pointer to location to return the data transfer mode. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_sym_k +
Signature: +
herr_t H5Pset_sym_k(hid_t plist, + int ik, + int lk + ) +
Purpose: +
Sets the size of parameters used to control the symbol table nodes. +
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. +

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. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 creationproperty 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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. Passing in a value of 0 for one of the + parameters retains the current value. +

+ ik is one half the rank of a tree that stores chunked raw + data. On average, such a tree will be 75% full, or have an + average rank of 1.5 times the value of ik. +

Parameters: +
+
hid_t plist +
IN: Identifier of property list to query. +
int ik +
IN: 1/2 rank of chunked storage B-tree. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_istore_k +
Signature: +
herr_t H5Pget_istore_k(hid_t plist, + int * ik + ) +
Purpose: +
Queries the 1/2 rank of an indexed storage B-tree. +
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. +

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. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_layout +
Signature: +
herr_t H5Pset_layout(hid_t plist, + H5D_layout_t layout + ) +
Purpose: +
Sets the type of storage used store the raw data for a dataset. +
Description: +
H5Pset_layout sets the type of storage used store the + raw data for a dataset. + This function is only valid for dataset creation property lists. + Valid parameters for layout are: +
    +
    H5D_COMPACT +
    Store raw data and object header contiguously in file. + This should only be used for very small amounts of raw + data (suggested less than 1KB). +
    H5D_CONTIGUOUS +
    Store raw data seperately from object header in one + large chunk in the file. +
    H5D_CHUNKED +
    Store raw data seperately from object header in one + large chunk in the file and store chunks of the raw + data in seperate locations in the file. +
+
Parameters: +
+
hid_t plist +
IN: Identifier of property list to query. +
H5D_layout_t layout +
IN: Type of storage layout for raw data. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_layout +
Signature: +
H5D_layout_t H5Pget_layout(hid_t plist) +
Purpose: +
Returns the layout of the raw data for a dataset. +
Description: +
H5Pget_layout returns the layout of the raw data for a dataset. + This function is only valid for dataset creation property lists. + Valid types for layout are: +
    +
    H5D_COMPACT +
    Raw data and object header stored contiguously in file. +
    H5D_CONTIGUOUS +
    Raw data stored seperately from object header in one + large chunk in the file. +
    H5D_CHUNKED +
    Raw data stored seperately from object header in + chunks in seperate locations in the file. +
+
Parameters: +
+
hid_t plist +
IN: Identifier for property list to query. +
+
Returns: +
Returns the layout type of a a dataset creation property list + if successful. + Otherwise returns H5D_LAYOUT_ERROR (-1). +
+ + +
+
+
Name: H5Pset_chunk +
Signature: +
herr_t H5Pset_chunk(hid_t plist, + int ndims, + const hsize_t * dim + ) +
Purpose: +
Sets the size of the chunks used to store a chunked layout dataset. +
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 isn't already. +
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. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_chunk +
Signature: +
int H5Pget_chunk(hid_t plist, + int max_ndims, + hsize_t * dims + ) +
Purpose: +
Retrieves the size of chunks for the raw data of a chunked layout dataset. +
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. +
Parameters: +
+
hid_t plist +
IN: Identifier of property list to query. +
int max_ndims +
OUT: Size of the dims array. +
hsize_t * dims +
OUT: Array to store the chunk dimensions. +
+
Returns: +
Returns chunk dimensionality successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_alignment +
Signature: +
herr_t H5Pset_alignment(hid_t plist, + hsize_t threshold, + hsize_t alignment + ) +
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 >= THRESHOLD bytes will be aligned on + an address which is a multiple of ALIGNMENT. The addresses + are relative to the end of the user block; the alignment is + calculated by subtracting the user block size from the + absolute file address and then adjusting the address to be a + multiple of ALIGNMENT. +

+ Default values for THRESHOLD and ALIGNMENT are one, implying + no alignment. Generally the default values will result in + the best performance for single-process access to the file. + For MPI-IO and other parallel systems, choose an alignment + which is a multiple of the disk block size. +

Parameters: +
+
hid_t plist +
IN: Identifier for a file access property list. +
hsize_t threshold +
IN: Threshhold value. +
hsize_t alignment +
IN: Alignment value. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_alignment +
Signature: +
herr_t H5Pget_alignment(hid_t plist, + hsize_t *threshold, + hsize_t *alignment + ) +
Purpose: +
Retrieves the current settings for alignment properties from a + file access property list. +
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). +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
hsize_t *threshold +
OUT: Pointer to location of return threshhold value. +
hsize_t *alignment +
OUT: Pointer to location of return alignment value. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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). +

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. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_external_count +
Signature: +
int H5Pget_external_count(hid_t plist, + ) +
Purpose: +
Returns the number of external files for a dataset. +
Description: +
H5Pget_external_count returns the number of external files + for the specified dataset. +
Parameters: +
+
hid_t plist +
IN: Identifier of a dataset creation property list. +
+
Returns: +
Returns the number of external files if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_external +
Signature: +
herr_t H5Pget_external(hid_t plist, + int idx, + size_t name_size, + char *name, + off_t *offset, + hsize_t *size + ) +
Purpose: +
Returns information about an external file. +
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()). +

+ 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 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: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_driver +
Signature: +
H5F_driver_t H5Pget_driver(hid_t plist, + ) +
Purpose: +
Returns a low-level file driver identifier. +
Description: +
H5Pget_driver returns the identifier of the + low-level file driver. Valid identifiers are: +
    +
  • H5F_LOW_STDIO (0) +
  • H5F_LOW_SEC2 (1) +
  • H5F_LOW_MPIO (2) +
  • H5F_LOW_CORE (3) +
  • H5F_LOW_SPLIT (4) +
  • H5F_LOW_FAMILY (5) +
+
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
+
Returns: +
Returns a low-level driver identifier if successful. + Otherwise returns H5F_LOW_ERROR (-1). +
+ + +
+
+
Name: H5Pset_stdio +
Signature: +
herr_t H5Pset_stdio(hid_t plist) +
Purpose: +
Sets the low level file driver to use the functions declared + in the stdio.h. +
Description: +
H5Pset_stdio sets the low level file driver to use + the functions declared + in the stdio.h file: fopen(), fseek() or fseek64(), fread(), + fwrite(), and fclose(). +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_stdio +
Signature: +
herr_t H5Pget_stdio(hid_t plist) +
Purpose: +
Determines whether the file access property list is set to + the stdio driver. +
Description: +
H5Pget_stdio checks to determine whether the + file access property list is set to the stdio driver. + In the future, additional arguments may be added to this + function to match those added to H5Pset_stdio(). +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
+
Returns: +
Returns SUCCEED (0) if the file access propety list is set + to the stdio driver. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Pset_sec2 +
Signature: +
herr_t H5Pset_sec2(hid_t plist, + ) +
Purpose: +
Sets the low-level file driver to use the declared functions. +
Description: +
H5Pset_sec2 sets the low-level file driver to use + the functions declared + in the unistd.h file: open(), lseek() or lseek64(), read(), + write(), and close(). +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_sec2 +
Signature: +
returntype H5Pget_sec2(hid_t plist) +
Purpose: +
Checks whether the file access propety list is set + to the sec2 driver. +
Description: +
H5Pget_sec2 checks to determine whether the + file access property list is set to the sec2 driver. + In the future, additional arguments may be + added to this function to match those added to H5Pset_sec2(). +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
+
Returns: +
Returns SUCCEED (0) if the file access propety list is set + to the sec2 driver. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Pset_core +
Signature: +
herr_t H5Pset_core(hid_t plist, + size_t increment + ) +
Purpose: +
Sets the low-level file driver to use malloc() and free(). +
Description: +
H5Pset_core sets the low-level file driver to use malloc() and free(). + This driver is restricted to temporary files which are not + larger than the amount of virtual memory available. The + INCREMENT argument determines the file block size and memory + will be allocated in multiples of INCREMENT bytes. A liberal + INCREMENT results in fewer calls to realloc() and probably + less memory fragmentation. +
Parameters: +
+
hid_t plist +
IN: Identifier of a file access property list. +
size_t increment +
IN: File block size in bytes. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: +
Signature: +
herr_t H5Pget_core(hid_t plist, + size_t *increment + ) +
Purpose: +
Determines whether the file access property list is set + to the core driver. +
Description: +
H5Pget_core checks to determine whether the + file access property list is set to the core driver. + On success, the block size is returned + through the INCREMENT argument if it isn't the null pointer. + In the future, additional arguments may be added to this + function to match those added to H5Pset_core(). +
Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
size_t *increment +
OUT: Pointer to a location to return the file block size (in bytes). +
+
Returns: +
Returns SUCCEED (0) if the file access propety list is set + to the core driver. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Pset_split +
Signature: +
herr_t H5Pset_split(hid_t plist, + const char *meta_ext, + hid_t meta_plist, + const char *raw_ext, + hid_t raw_plist + ) +
Purpose: +
Sets the low-level driver to split meta data from raw data. +
Description: +
H5Pset_split sets the low-level driver to + split meta data from raw data, storing meta data in one file and + raw data in another file. The meta file will have a name + which is formed by adding meta_extension (recommended + default value: .meta) to the end of the base name + and will be accessed according to the meta_properties. + The raw file will have a name which is formed by appending + raw_extension (recommended default value: + .raw) to the base name and will be accessed according + to the raw_properties. + Additional parameters may be added to this function in the future. +
Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
const char *meta_ext +
IN: Name of the extension for the metafile filename. + Recommended default value: .meta. +
hid_t meta_plist +
IN: Identifier of the meta file access property list. +
const char *raw_ext +
IN: Name extension for the raw file filename. + Recommended default value: .raw. +
hid_t raw_plist +
IN: Identifier of the raw file access property list. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_split +
Signature: +
herr_t H5Pget_split(hid_t plist, + size_t meta_ext_size, + char *meta_ext, + hid_t *meta_properties, + size_t raw_ext_size, + char *raw_ext, + hid_t *raw_properties + ) +
Purpose: +
Determines whether the file access property list is set + to the split driver. +
Description: +
H5Pget_split checks to determine whether the file + access property list is set to the split driver. + On successful return, + meta_properties and raw_properties will + point to copies of the meta and raw access property lists + which should be closed by calling H5Pclose() when + the application is finished with them, but if the meta and/or + raw file has no property list then a negative value is + returned for that property list identifier. Also, if + meta_extension and/or raw_extension are + non-null pointers, at most meta_ext_size or + raw_ext_size characters of the meta or raw file name + extension will be copied to the specified buffer. If the + actual name is longer than what was requested then the result + will not be null terminated (similar to + strncpy()). In the future, additional arguments + may be added to this function to match those added to + H5Pset_split(). +
Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
size_t meta_ext_size +
IN: Number of characters of the meta file extension to be + copied to the meta_ext buffer. +
OUT *meta_ext +
IN: Meta file extension. +
hid_t *meta_properties +
OUT: Pointer to a copy of the meta file access property list. +
size_t raw_ext_size +
IN: Number of characters of the raw file extension to be + copied to the raw_ext buffer. +
char *raw_ext +
OUT: Raw file extension. +
hid_t *raw_properties +
OUT: Pointer to a copy of the raw file access property list. +
+
Returns: +
Returns SUCCEED (0) if the file access propety list is set + to the split driver. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Pset_family +
Signature: +
herr_t H5Pset_family(hid_t plist, + hsize_t memb_size, + hid_t memb_plist + ) +
Purpose: +
Sets the file access properties list to the family + driver. +
Description: +
H5Pset_family sets the file access properties + to use the family + driver; any previously defined driver properties are erased + from the property list. Each member of the file family will + use member_properties as its file access property + list. The memb_size argument gives the logical size + in bytes of each family member but the actual size could be + smaller depending on whether the file contains holes. The + member size is only used when creating a new file or + truncating an existing file; otherwise the member size comes + from the size of the first member of the family being + opened. Note: if the size of the off_t type is + four bytes then the maximum family member size is usually + 2^31-1 because the byte at offset 2,147,483,647 is generally + inaccessable. Additional parameters may be added to this + function in the future. +
Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
hsize_t memb_size +
IN: Logical size, in bytes, of each family member. +
hid_t memb_plist +
IN: Identifier of the file access property list + for each member of the family. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_family +
Signature: +
herr_t H5Pget_family(hid_t tid, + hsize_t *memb_size, + hid_t *memb_plist + ) +
Purpose: +
Determines whether the file access property list + is set to the family driver. +
Description: +
H5Pget_family checks to determine whether the + file access property list is set to the family driver. + On successful return, + access_properties will point to a copy of the member + access property list which should be closed by calling + H5Pclose() when the application is finished with + it. If memb_size is non-null then it will contain + the logical size in bytes of each family member. In the + future, additional arguments may be added to this function to + match those added to H5Pset_family(). +
Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
hsize_t *memb_size +
OUT: Logical size, in bytes, of each family member. +
hid_t *memb_plist +
OUT: Identifier of the file access property list + for each member of the family. +
+
Returns: +
Returns SUCCEED (0) if the file access propety list is set + to the family driver. + Otherwise returns FAIL (-1). +
+ + +
+
+
Name: H5Pset_cache +
Signature: +
herr_t H5Pset_cache(hid_t plist, + int mdc_nelmts, + size_t rdcc_nbytes, + double rdcc_w0 + ) +
Purpose: +
Sets the number of elements in the meta data cache and the + total number of bytes in the raw data chunk cache. +
Description: +
H5Pset_cache sets the number of elements (objects) in the meta data cache and the + total number of bytes in the raw data chunk cache. +

+ Sets or queries the meta data cache and raw data chunk cache + parameters. The plist is a file access property + list. The number of elements (objects) in the meta data cache + is mdc_nelmts. The total size of the raw data chunk + cache and the preemption policy is rdcc_nbytes and + w0. For H5Pget_cache() any (or all) of + the pointer arguments may be null pointers. +

+ The RDCC_W0 value should be between 0 and 1 inclusive and + indicates how much chunks that have been fully read are + favored for preemption. A value of zero means fully read + chunks are treated no differently than other chunks (the + preemption is strictly LRU) while a value of one means fully + read chunks are always preempted before other chunks. +

Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
int mdc_nelmts +
IN: Number of elements (objects) in the meta data cache. +
size_t rdcc_nbytes +
IN: Total size of the raw data chunk cache, in bytes. +
double rdcc_w0 +
IN: Preemption policy. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_cache +
Signature: +
herr_t H5Pget_cache(hid_t plist, + int *mdc_nelmts, + size_t *rdcc_nbytes, + double *rdcc_w0 + ) +
Purpose: +
Retrieves maximun sizes of meta data cache and RDCC_WO. +
Description: +
Retrieves the maximum possible number of elements in the meta + data cache and the maximum possible number of bytes and the + RDCC_W0 value in the raw data chunk cache. Any (or all) + arguments may be null pointers in which case the corresponding + datum is not returned. +
Parameters: +
+
hid_t plist +
IN: Identifier of the file access property list. +
int *mdc_nelmts +
IN/OUT: Number of elements (objects) in the meta data 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_buffer +
Signature: +
herr_t H5Pset_buffer(hid_t plist, + size_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 supply pointers to application-allocated buffers. + If the buffer size is smaller than the entire amount of data + being transfered between application and file, and a type + conversion buffer or background buffer is required then + strip mining will be used. However, certain restrictions + apply for the size of buffer which can be used for strip + mining. For instance, when strip mining a 100x200x300 + hyperslab of a simple data space the buffer must be large + enough to hold a 1x200x300 slab. +

+ 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: Identifier for the dataset transfer property list. +
size_t size +
IN: Size for 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 SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_buffer +
Signature: +
size_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 if successful; + otherwise 0 on failure. +
+ + +
+
+
Name: H5Pset_preserve +
Signature: +
herr_t H5Pset_preserve(hid_t plist, + hbool_t status + ) +
Purpose: +
Sets the dataset transfer property list status to TRUE or FALSE. +
Description: +
H5Pset_preserve sets the + dataset transfer property list status to TRUE or FALSE. +

+ When reading or writing compound data types and the + destination is partially initialized and the read/write is + intended to initialize the other members, one must set this + property to TRUE. Otherwise the I/O pipeline treats the + destination datapoints as completely uninitialized. +

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). +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 +
IN: Identifier for the dataset transfer property list. +
+
Returns: +
Returns TRUE or FALSE if successful; + otherwise FAIL (-1). +
+ + +
+
+
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 compresion 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 Compression + in the HDF5 User's Guide for further information. +

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. +
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. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_compression +
Signature: +
H5Z_method_t H5Pget_compression(hid_t plist, + unsigned int *flags, + size_t *cd_size, + void *client_data + ) +
Purpose: +
Gets compression method. +
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.
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. +
+
Returns: +
Returns compression method if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pset_deflate +
Signature: +
herr_t H5Pset_deflate(hid_t plist, + int level + ) +
Purpose: +
Sets compression method and compression level. +
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 between zero and 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 plist +
IN: Identifier for the dataset creation property list. +
int level +
IN: Compression level. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+
+
Name: H5Pget_deflate +
Signature: +
int H5Pget_deflate(hid_t plist + ) +
Purpose: +
Returns the deflate compression level from a dataset creation + property list. +
Description: +
H5Pget_deflate returns the deflate compression level + from a dataset creation property list that uses that method. +
Parameters: +
+
hid_t plist +
IN: Identifier for the dataset creation property list. +
+
Returns: +
Returns compression level, a value between 0 and 9, if successful. + Otherwise returns FAIL (-1). +
+ + +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 8 July 1998 + + + diff --git a/doc/src/RM_H5S.html b/doc/src/RM_H5S.html new file mode 100644 index 0000000..903d720 --- /dev/null +++ b/doc/src/RM_H5S.html @@ -0,0 +1,291 @@ + + +HDF5/H5S Draft API Specification + + + + +
+

H5S: Dataspace Interface

+
+ +

Dataspace Object API Functions

+ +These functions create and manipulate the dataspace in which to store the +elements of a dataset. + + + +
+ +       + +       + +
+ +
+ +
+
Name: H5Screate_simple +
Signature: +
hid_t H5Screate_simple(int rank, + const hsize_t * dims, + const hsize_t * maxdims + ) +
Description: +
This function creates a new simple data space object and opens it for + access. The rank is the number of dimensions used in the + dataspace. The dims argument is the size of the simple + dataset and the maxdims argument is the upper limit on the + size of the dataset. maxdims may be the null pointer in + which case the upper limit is the same as dims. If an + element of maxdims is zero then the corresponding dimension + is unlimited, otherwise no element of maxdims should be + smaller than the corresponding element of dims. The + dataspace ID returned from this function should be released with + H5Sclose or resource leaks will occur. +
Parameters: +
+
int rank +
Number of dimensions of dataspace. +
const hsize_t * dims +
An array of the size of each dimension. +
const hsize_t * maxdims +
An array of the maximum size of each dimension. +
+
Returns: +
A dataspace ID on success, negative on failure. +
+ +
+
+
Name: H5Scopy +
Signature: +
hid_t H5Scopy(hid_t space_id + ) +
Description: +
This function copies a dataspace. The dataspace ID returned from this + function should be released with H5Sclose or resource leaks will occur. +
Parameters: +
+
hid_t space_id +
ID of dataspace to copy. +
+
Returns: +
A dataspace ID on success, negative on failure. +
+ +
+
+
Name: H5Sget_npoints +
Signature: +
hsize_t H5Sget_npoints(hid_t space_id) +
Description: +
This function determines the number of elements in a dataspace. For + example, a simple 3-dimensional dataspace with dimensions 2, 3 and 4 + would have 24 elements. +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to query +
+
Returns: +
Number of elements in the dataspace, 0 on failure +
+ +
+
+
Name: H5Sget_ndims +
Signature: +
int H5Sget_ndims(hid_t space_id) +
Description: +
This function determines the dimensionality (or rank) of a dataspace. +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to query +
+
Returns: +
Number of dimensions in the dataspace, negative on failure +
+ +
+
+
Name: H5Sget_dims +
Signature: +
int H5Sget_dims(hid_t space_id, + hsize_t *dims, + hsize_t *maxdims + ) +
Description: +
This function returns the size of each dimension in a dataspace through + the dims parameter. +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to query +
hsize_t *dims +
Pointer to array to store the size of each dimension. +
hsize_t *maxdims +
Pointer to array to store the maximum size of each dimension. +
+
Returns: +
Number of dimensions in the dataspace, negative on failure +
+ +
+
+
Name: H5Sis_simple +
Signature: +
hbool_t H5Sis_simple(hid_t space_id) +
Description: +
This function determines whether a dataspace object is a simple + dataspace or not. [Currently, all dataspace objects are simple + dataspaces, complex dataspace support will be added in the future] +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to query +
+
Returns: +
TRUE or FALSE on success, negative on failure +
+ +
+
+
Name: H5Sset_space +
Signature: +
herr_t H5Sset_space(hid_t space_id, + uint32 rank, + uint32 *dims + ) +
Description: +
This function determines the number of dimensions and the size of each + dimension for the space that a dataset is stored within. This function + only creates simple dataspace objects. Setting the rank to a + value of zero allows scalar objects to be created. Dimensions are + specified from slowest to fastest changing in the dims + array (i.e. 'C' order). Setting the size of a dimension to zero + indicates that the dimension is of unlimited size and should be allowed + to expand. Currently, only the first dimension in the array (the + slowest) may be unlimited in size. + [Currently, all dataspace objects are simple + dataspaces, complex dataspace support will be added in the future] +
Parameters: +
+
hid_t space_id +
ID of the dataspace object. +
uint32 rank +
The number of dimensions the object is composed of. +
uint32 * dims +
An array of the size of each dimension. (NULL for scalar objects) +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Sset_hyperslab +
Signature: +
herr_t H5Sset_hyperslab(hid_t space_id, + const hssize_t *start, + const hsize_t *count, + const hsize_t *stride + ) +
Description: +
This function selects a hyperslab from a simple dataspace. The stride + array may be used to sub-sample the hyperslab chosen, a value of 1 in each + position of the stride array selects contiguous elements in the array, + a value of 2 selects every other element, etc. If the stride parameter is + set to NULL, a contiguous hyperslab is chosen. The values in the start and + count arrays may be negative, to allow for selecting hyperslabs in chunked + datasets which extend in arbitrary directions. +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to set hyperslab in. +
const hssize_t *start +
Pointer to array of starting location for hyperslab. +
const hsize_t *count +
Pointer to array of magnitude of hyperslab. +
const hsize_t *stride +
Pointer to array of stride of hyperslab. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Sget_hyperslab +
Signature: +
int H5Sget_hyperslab(hid_t space_id, + hssize_t *start, + hsize_t *count, + hsize_t *stride + ) +
Description: +
This function retrieves information about the hyperslab from a simple + dataspace. If no hyperslab has been defined then the hyperslab is the + same as the entire array. +
Parameters: +
+
hid_t space_id +
ID of the dataspace object to set hyperslab in. +
hssize_t *start +
Pointer to array to store starting location of hyperslab. +
hsize_t *count +
Pointer to array to store magnitude of hyperslab. +
hsize_t *stride +
Pointer to array to store stride of hyperslab. +
+
Returns: +
Hyperslab dimensionality on success, negative on failure. +
+ +
+
+
Name: H5Sclose +
Signature: +
herr_t H5Sclose(hid_t space_id + ) +
Description: +
This function releases a dataspace. Further access through the dataspace + ID is illegal. Failure to release a dataspace with this call will + result in resource leaks. +
Parameters: +
+
hid_t space_id +
ID of dataspace to release. +
+
Returns: +
zero/negative +
+ +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 29 June 1998 + + + diff --git a/doc/src/RM_H5T.html b/doc/src/RM_H5T.html new file mode 100644 index 0000000..46fe6fc --- /dev/null +++ b/doc/src/RM_H5T.html @@ -0,0 +1,1323 @@ + + +HDF5/H5T Draft API Specification + + + + +
+

H5T: Datatype Interface

+
+ +

Datatype Object API Functions

+ +These functions create and manipulate the datatype which describes elements +of a dataset. + + + +
+ +       + +       + +
+ +
+ +
+
Name: H5Tcreate +
Signature: +
hid_t H5Tcreate(H5T_class_t class, + size_tsize + ) +
Description: +
This function creates a new dataype of the specified class with the + specified number of bytes. Currently, only the H5T_COMPOUND + datatype class is supported with this function, use H5Tcopy + to create integer or floating-point datatypes. The datatype ID + returned from this function should be released with H5Tclose or resource + leaks will result. +
Parameters: +
+
H5T_class_t class +
Class of datatype to create. +
size_t size +
The number of bytes in the datatype to create. +
+
Returns: +
Datatype ID on success, negative on failure. +
+ +
+
+
Name: H5Tcopy +
Signature: +
hid_t H5Tcopy(hid_t type_id + ) +
Description: +
This function copies an existing datatype. The datatype ID returned + should be released with H5Tclose or resource leaks will occur. Native + datatypes supported by the library are: +
    +
    H5T_NATIVE_CHAR +
    Native character type, declare dataset array as 'char' +
    H5T_NATIVE_UCHAR +
    Native unsigned character type, declare dataset array as 'unsigned char' +
    H5T_NATIVE_SHORT +
    Native short type, declare dataset array as 'short' +
    H5T_NATIVE_USHORT +
    Native unsigned short type, declare dataset array as 'unsigned short' +
    H5T_NATIVE_INT +
    Native int type, declare dataset array as 'int' +
    H5T_NATIVE_UINT +
    Native unsigned int type, declare dataset array as 'unsigned int' +
    H5T_NATIVE_LONG +
    Native long type, declare dataset array as 'unsigned long' +
    H5T_NATIVE_ULONG +
    Native unsigned long type, declare dataset array as 'unsigned long' +
    H5T_NATIVE_LLONG +
    Native long long type, declare dataset array as 'unsigned long long' +
    H5T_NATIVE_ULLONG +
    Native unsigned long long type, declare dataset array as 'unsigned long long' +
    H5T_NATIVE_INT8 +
    Native signed 8-bit type, declare dataset array as 'int8' +
    H5T_NATIVE_UINT8 +
    Native unsigned 8-bit type, declare dataset array as 'uint8' +
    H5T_NATIVE_INT16 +
    Native signed 16-bit type, declare dataset array as 'int16' +
    H5T_NATIVE_UINT16 +
    Native unsigned 16-bit type, declare dataset array as 'uint16' +
    H5T_NATIVE_INT32 +
    Native signed 32-bit type, declare dataset array as 'int32' +
    H5T_NATIVE_UINT32 +
    Native unsigned 32-bit type, declare dataset array as 'uint32' +
    H5T_NATIVE_INT64 +
    Native signed 64-bit type, declare dataset array as 'uint64' +
    H5T_NATIVE_UINT64 +
    Native unsigned 64-bit type, declare dataset array as 'uint64' +
    H5T_NATIVE_FLOAT +
    Native single-precision float type, declare dataset array as 'float' +
    H5T_NATIVE_DOUBLE +
    Native double-precision float type, declare dataset array as 'double' +
+
Parameters: +
+
hid_t type_id +
ID of datatype to copy. +
+
Returns: +
Datatype ID on success, negative on failure. +
+ +
+
+
Name: H5Tequal +
Signature: +
hbool_t H5Tequal(hid_t type_id1, + hid_ttype_id2 + ) +
Description: +
This function determines if two datatype IDs refer to the same + datatype. +
Parameters: +
+
hid_t type_id1 +
ID of datatype to compare. +
hid_t type_id2 +
ID of datatype to compare. +
+
Returns: +
TRUE/FALSE/negative +
+ +
+
+
Name: H5Tlock +
Signature: +
herr_t H5Tlock(hid_t type_id + ) +
Description: +
This function locks a type, making it read-only and non-destrucible. + This is normally done by the library for predefined data types so the + application doesn't inadvertently change or delete a predefined type. + Once a data type is locked it can never be unlocked. +
Parameters: +
+
hid_t type_id +
ID of datatype to lock. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_class +
Signature: +
H5T_class_t H5Tget_class(hid_t type_id + ) +
Description: +
This function returns the base class of a datatype. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Non-negative type class on success, negative on failure. +
+ +
+
+
Name: H5Tget_size +
Signature: +
size_t H5Tget_size(hid_t type_id + ) +
Description: +
This function returns the size of a datatype in bytes. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Positve size in bytes on success, 0 on failure. +
+ +
+
+
Name: H5Tset_size +
Signature: +
herr_t H5Tset_size(hid_t type_id, + size_tsize + ) +
Description: +
This function sets the total size in bytes for an atomic data type (this + operation is not permitted on compound data types). If the size is + decreased so that the significant bits of the data type extend beyond + the edge of the new size, then the `offset' property is decreased + toward zero. If the `offset' becomes zero and the significant + bits of the data type still hang over the edge of the new size, then + the number of significant bits is decreased. + Adjusting the size of an H5T_STRING automatically sets the precision + to 8*size. All data types have a positive size. +
Parameters: +
+
hid_t type_id +
ID of datatype to change size. +
size_t size +
Size in bytes to modify datatype. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_order +
Signature: +
H5T_order_t H5Tget_order(hid_t type_id + ) +
Description: +
This function returns the byte order of an atomic datatype. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Byte order constant on success, negative on failure +
+ +
+
+
Name: H5Tset_order +
Signature: +
herr_t H5Tset_order(hid_t type_id, + H5T_order_torder + ) +
Description: +
This function sets the byte ordering of an atomic datatype. + Byte orderings currently supported are: +
    +
    H5T_ORDER_LE +
    Little-endian byte ordering (default) +
    H5T_ORDER_BE +
    Big-endian byte ordering +
    H5T_ORDER_Vax +
    VAX-endianness byte ordering (not currently supported) +
+
Parameters: +
+
hid_t type_id +
ID of datatype to set. +
H5T_order_t order +
Byte ordering constant. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_precision +
Signature: +
size_t H5Tget_precision(hid_t type_id + ) +
Description: +
This function returns the precision of an atomic data type. The + precision is the number of significant bits which, unless padding is + present, is 8 times larger than the value returned by H5Tget_size(). +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Number of significant bits on success, 0 on failure +
+ +
+
+
Name: H5Tset_precision +
Signature: +
herr_t H5Tset_precision(hid_t type_id, + size_tprecision + ) +
Description: +
This function sets the precision of an atomic data type. The precision + is the number of significant bits which, unless padding is present, is 8 + times larger than the value returned by H5Tget_size(). +

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

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

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

Parameters: +
+
hid_t type_id +
ID of datatype to set. +
size_t precision +
Number of bits of precision for datatype. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_offset +
Signature: +
size_t H5Tget_offset(hid_t type_id + ) +
Description: +
This function retrieves the bit offset of the first significant bit. + The signficant bits of an atomic datum can be offset from the beginning + of the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be layed out in + memory as (from small byte address toward larger byte addresses): +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Byte PositionBig-Endian Offset=0Big-Endian Offset=16Little-Endian Offset=0Little-Endian Offset=16
0:[ pad][0x11][0x22][ pad]
1:[ pad][0x22][0x11][ pad]
2:[0x11][ pad][ pad][0x22]
3:[0x22][ pad][ pad][0x11]
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Positive offset value on success, 0 on failure. +
+ +
+
+
Name: H5Tset_offset +
Signature: +
herr_t H5Tset_offset(hid_t type_id, + size_t offset + ) +
Description: +
This function sets the bit offset of the first significant bit. The + signficant bits of an atomic datum can be offset from the beginning of + the memory for that datum by an amount of padding. The `offset' + property specifies the number of bits of padding that appear to the + "right of" the value. That is, if we have a 32-bit datum with 16-bits + of precision having the value 0x1122 then it will be layed out in + memory as (from small byte address toward larger byte addresses): +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Byte PositionBig-Endian Offset=0Big-Endian Offset=16Little-Endian Offset=0Little-Endian Offset=16
0:[ pad][0x11][0x22][ pad]
1:[ pad][0x22][0x11][ pad]
2:[0x11][ pad][ pad][0x22]
3:[0x22][ pad][ pad][0x11]
+ +

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

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

Parameters: +
+
hid_t type_id +
ID of datatype to set. +
size_t offset +
Offset of first significant bit. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_pad +
Signature: +
herr_t H5Tget_pad(hid_t type_id, + H5T_pad_t * lsb, + H5T_pad_t * msb + ) +
Description: +
This function retrieves the padding type of the least and most-significant + bit padding. Valid types are: +
    +
    H5T_PAD_ZERO +
    Set background to zeros. +
    H5T_PAD_ONE +
    Set background to ones. +
    H5T_PAD_BACKGROUND +
    Leave background alone. +
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
H5T_pad_t * lsb +
Pointer to location to return least-significant bit padding type. +
H5T_pad_t * msb +
Pointer to location to return most-significant bit padding type. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tset_pad +
Signature: +
herr_t H5Tset_pad(hid_t type_id, + H5T_pad_t lsb, + H5T_pad_t msb + ) +
Description: +
This function sets the least and most-significant bits padding types. +
    +
    H5T_PAD_ZERO +
    Set background to zeros. +
    H5T_PAD_ONE +
    Set background to ones. +
    H5T_PAD_BACKGROUND +
    Leave background alone. +
+
Parameters: +
+
hid_t type_id +
ID of datatype to set. +
H5T_pad_t lsb +
Padding type for least-significant bits. +
H5T_pad_t msb +
Padding type for most-significant bits. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_sign +
Signature: +
H5T_sign_t H5Tget_sign(hid_t type_id + ) +
Description: +
This function retrieves the sign type for an integer type. + Valid types are: +
    +
    H5T_SGN_NONE +
    Unsigned integer type. +
    H5T_SGN_2 +
    Two's complement signed integer type. +
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Non-negative sign type on success, negative on failure +
+ +
+
+
Name: H5Tset_sign +
Signature: +
herr_t H5Tset_sign(hid_t type_id, + H5T_sign_t sign + ) +
Description: +
This function sets the sign proprety for an integer type. +
    +
    H5T_SGN_NONE +
    Unsigned integer type. +
    H5T_SGN_2 +
    Two's complement signed integer type. +
+
Parameters: +
+
hid_t type_id +
ID of datatype to set. +
H5T_sign_t sign +
Sign type. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_fields +
Signature: +
herr_t H5Tget_fields(hid_t type_id, + size_t * epos, + size_t * esize, + size_t * mpos, + size_t * msize + ) +
Description: +
This function retrieves information about the locations of the various + bit fields of a floating point data type. The field positions are bit + positions in the significant region of the data type. Bits are + numbered with the least significant bit number zero. + Any (or even all) of the arguments can be null pointers. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
size_t * epos +
Pointer to location to return exponent bit-position. +
size_t * esize +
Pointer to location to return size of exponent in bits. +
size_t * mpos +
Pointer to location to return mantissa bit-position. +
size_t * msize +
Pointer to location to return size of mantissa in bits. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tset_fields +
Signature: +
herr_t H5Tset_fields(hid_t type_id, + size_t epos, + size_t esize, + size_t mpos, + size_t msize + ) +
Description: +
This function sets the locations and sizes of the various floating + point bit fields. The field positions are bit positions in the + significant region of the data type. Bits are numbered with the least + significant bit number zero. + +

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

Parameters: +
+
hid_t type_id +
ID of datatype to set. +
size_t epos +
Exponent bit position. +
size_t esize +
Size of exponent in bits. +
size_t mpos +
Mantissa bit position. +
size_t msize +
Size of mantissa in bits. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_ebias +
Signature: +
size_t H5Tget_ebias(hid_t type_id + ) +
Description: +
This function retrieves the exponent bias of a floating-point type. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Positive value on success, 0 on failure. +
+ +
+
+
Name: H5Tset_ebias +
Signature: +
herr_t H5Tset_ebias(hid_t type_id, + size_t ebias + ) +
Description: +
This function sets the exponent bias of a floating-point type. +
Parameters: +
+
hid_t type_id +
ID of datatype to set. +
size_t ebias +
Exponent bias value. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_norm +
Signature: +
H5T_norm_t H5Tget_norm(hid_t type_id + ) +
Description: +
This function retrieves the mantissa normalization of a floating-point + datatype. Valid normalization values are: +
    +
    H5T_NORM_IMPLIED +
    MSB of mantissa isn't stored, always 1 +
    H5T_NORM_MSBSET +
    MSB of mantissa is always 1 +
    H5T_NORM_NONE +
    Mantissa is not normalized +
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Non-negative normalization type on success, negative on failure +
+ +
+
+
Name: H5Tset_norm +
Signature: +
herr_t H5Tset_norm(hid_t type_id, + H5T_norm_t norm + ) +
Description: +
This function sets the mantissa normalization of a floating-point + datatype. Valid normalization values are: +
    +
    H5T_NORM_IMPLIED +
    MSB of mantissa isn't stored, always 1 +
    H5T_NORM_MSBSET +
    MSB of mantissa is always 1 +
    H5T_NORM_NONE +
    Mantissa is not normalized +
+
Parameters: +
+
hid_t type_id +
ID of datatype to set. +
H5T_norm_t norm +
Mantissa normalization type. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_inpad +
Signature: +
H5T_pad_t H5Tget_inpad(hid_t type_id + ) +
Description: +
This function retrieves the internal padding type for unused bits in + floating-point datatypes. + Valid padding values are: +
    +
    H5T_PAD_ZERO +
    Set background to zeros. +
    H5T_PAD_ONE +
    Set background to ones. +
    H5T_PAD_BACKGROUND +
    Leave background alone. +
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Non-negative padding type on success, negative on failure +
+ +
+
+
Name: H5Tset_inpad +
Signature: +
herr_t H5Tset_inpad(hid_t type_id, + H5T_pad_t inpad + ) +
Description: +
If any internal bits of a floating point type are unused + (that is, those significant bits which are not part of the + sign, exponent, or mantissa) then they will be filled + according to the value of this property. + Valid padding values are: +
    +
    H5T_PAD_ZERO +
    Set background to zeros. +
    H5T_PAD_ONE +
    Set background to ones. +
    H5T_PAD_BACKGROUND +
    Leave background alone. +
+
Parameters: +
+
hid_t type_id +
ID of datatype to modify. +
H5T_pad_t pad +
Padding type. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_cset +
Signature: +
H5T_cset_t H5Tget_cset(hid_t type_id + ) +
Description: +
This function retrieves the character set type of a string datatype. + Valid character set values are: +
    +
    H5T_CSET_ASCII +
    Character set is US ASCII +
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Non-negative character set type on success, negative on failure +
+ +
+
+
Name: H5Tset_cset +
Signature: +
herr_t H5Tset_cset(hid_t type_id, + H5T_cset_t cset + ) +
Description: +
HDF5 is able to distinguish between character sets of different + nationalities and to convert between them to the extent possible. + Valid character set values are: +
    +
    H5T_CSET_ASCII +
    Character set is US ASCII +
+
Parameters: +
+
hid_t type_id +
ID of datatype to modify. +
H5T_cset_t cset +
Character set type. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_strpad +
Signature: +
H5T_str_t H5Tget_strpad(hid_t type_id + ) +
Description: +
This function retrieves the string padding method for a string datatype. + Valid string padding values are: +
    +
    H5T_STR_NULL +
    Pad with zeros (as C does) +
    H5T_STR_SPACE +
    Pad with spaces (as FORTRAN does) +
+
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Non-negative string padding type on success, negative on failure +
+ +
+
+
Name: H5Tset_strpad +
Signature: +
herr_t H5Tset_strpad(hid_t type_id, + H5T_str_t strpad + ) +
Description: +
The method used to store character strings differs with the programming + language: C usually null terminates strings while Fortran + left-justifies and space-pads strings. This property defines the + storage mechanism for the string. + Valid string padding values are: +
    +
    H5T_STR_NULL +
    Pad with zeros (as C does) +
    H5T_STR_SPACE +
    Pad with spaces (as FORTRAN does) +
+
Parameters: +
+
hid_t type_id +
ID of datatype to modify. +
H5T_str_t strpad +
String padding type. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tget_nmembers +
Signature: +
intn H5Tget_nmembers(hid_t type_id + ) +
Description: +
This function retrieves the number of fields a compound datatype has. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
+
Returns: +
Number of members datatype has on success, negative on failure +
+ +
+
+
Name: H5Tget_member_name +
Signature: +
char * H5Tget_member_name(hid_t type_id, + intn fieldno + ) +
Description: +
This function retrieves the name of a field of a compound data type. + Fields are stored in no particular order with numbers 0 through N-1 + where N is the value returned by H5Tget_nmembers(). The name of the + field is allocated with malloc() and the caller is responsible for + freeing the memory used by the name. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
intn fieldno +
Field number (indexed from 0) of the field name to retrieve. +
+
Returns: +
Valid pointer on success, NULL on failure +
+ +
+
+
Name: H5Tget_member_dims +
Signature: +
int H5Tget_member_dims(hid_t type_id, + intn fieldno, + size_t * dims, + int * perm + ) +
Description: +
This function returns the dimensionality of the field. The dimensions + and permuation vector are returned through arguments dims + and perm, both arrays of at least four elements. Either + (or even both) may be null pointers. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
intn fieldno +
Field number (indexed from 0) of the field dims to retrieve. +
size_t * dims +
Pointer to buffer to store the dimensions of the field. +
int * perm +
Pointer to buffer to store the permutation vector of the field. +
+
Returns: +
Number of dimensions on success, negative on failure. +
+ +
+
+
Name: H5Tget_member_type +
Signature: +
hid_t H5Tget_member_type(hid_t type_id, + intn fieldno + ) +
Description: +
This function returns the data type of the specified member. The caller + should invoke H5Tclose() to release resources associated with the type. +
Parameters: +
+
hid_t type_id +
ID of datatype to query. +
intn fieldno +
Field number (indexed from 0) of the field type to retrieve. +
+
Returns: +
The ID of a copy of the datatype of the field, negative on failure. +
+ +
+
+
Name: H5Tinsert +
Signature: +
herr_t H5Tinsert(hid_t type_id, + const char * name, + off_t offset, + hid_t field_id + ) +
Description: +
This function adds another member to the compound data type + type_id. The new member has a name which + must be unique within the compound data type. The offset + argument defines the start of the member in an instance of the compound + data type, and field_id is the type of the new member. + +

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

Parameters: +
+
hid_t type_id +
ID of compound datatype to modify. +
const char * name +
Name of the field to insert. +
off_t offset +
Offset in memory structure of the field to insert. +
hid_t field_id +
Datatype ID of the field to insert. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tpack +
Signature: +
herr_t H5Tpack(hid_t type_id + ) +
Description: +
This function recursively removes padding from within a compound + datatype to make it more efficient (space-wise) to store that data. +
Parameters: +
+
hid_t type_id +
ID of datatype to modify. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tregister_hard +
Signature: +
herr_t H5Tregister_hard(const char + * name, hid_t src_id, + hid_t dst_id, + H5T_conv_t func + ) +
Description: +
This function registers a hard conversion function for a data type + conversion path. The path is specified by the source and destination + datatypes src_id and dst_id. A conversion + path can only have one hard function, so func replaces any + previous hard function. +

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

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

Parameters: +
+
const char * name +
Name displayed in diagnostic output. +
hid_t src_id +
ID of source datatype. +
hid_t dst_id +
ID of destination datatype. +
H5T_conv_t func +
Function to convert between source and destination datatypes. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tregister_soft +
Signature: +
herr_t H5Tregister_soft(const char + * name, hid_t src_id, + hid_t dst_id, + H5T_conv_t func + ) +
Description: +
This function registers a soft conversion function by adding it to the + end of the master soft list and replacing the soft function in all + applicable existing conversion paths. The name + is used only for debugging and should be a short identifier + for the function. +

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

Parameters: +
+
const char * name +
Name displayed in diagnostic output. +
hid_t src_id +
ID of source datatype. +
hid_t dst_id +
ID of destination datatype. +
H5T_conv_t func +
Function to convert between source and destination datatypes. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tunregister +
Signature: +
herr_t H5Tunregister(H5T_conv_t func + ) +
Description: +
This function removes a conversion function from all conversion paths. +

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

Parameters: +
+
H5T_conv_t func +
Function to remove from conversion paths. +
+
Returns: +
zero/negative +
+ +
+
+
Name: H5Tclose +
Signature: +
herr_t H5Tclose(hid_t type_id + ) +
Description: +
This function releases a datatype. Further access through the datatype + ID is illegal. Failure to release a datatype with this call will + result in resource leaks. +
Parameters: +
+
hid_t type_id +
ID of datatype to release. +
+
Returns: +
zero/negative +
+ + + +
+
+UNUSED PORTIONS OF EMAIL NOTES. +
+.... in left margin indicates where material was + pulled out for inclusion above. +
+
+
+
+Elena> Datatype Interface:
+Elena> Do we have description of the named datatypes somewhere?
+
+>From Datatypes.html...
+
+html> 7. Sharing Data Types among Datasets
+html> 
+html> If a file has lots of datasets which have a common data type
+html> then the file could be made smaller by having all the datasets
+html> share a single data type.  Instead of storing a copy of the data
+html> type in each dataset object header, a single data type is stored
+html> and the object headers point to it. The space savings is
+html> probably only significant for datasets with a compound data type
+html> since the simple data types can be described with just a few
+html> bytes anyway.
+html> 
+html> To create a bunch of datasets that share a single data type just
+html> create the datasets with a committed (named) data type.
+html> 
+html>  To create two datasets that share a common data type one just
+html>  commits the data type, giving it a name, and then uses that
+html>  data type to create the datasets.
+html> 
+html>  hid_t t1 = ...some transient type...;
+html>  H5Tcommit (file, "shared_type", t1);
+html>  hid_t dset1 = H5Dcreate (file, "dset1", t1, space, H5P_DEFAULT);
+html>  hid_t dset2 = H5Dcreate (file, "dset2", t1, space, H5P_DEFAULT);
+html>                
+html> 
+html>  And to create two additional datasets later which share the
+html>  same type as the first two datasets:
+html> 
+html>  hid_t dset1 = H5Dopen (file, "dset1");
+html>  hid_t t2 = H5Dget_type (dset1);
+html>  hid_t dset3 = H5Dcreate (file, "dset3", t2, space, H5P_DEFAULT);
+html>  hid_t dset4 = H5Dcreate (file, "dset4", t2, space, H5P_DEFAULT);
+html>                
+html> 
+html>                                     Example: Shared Types
+
+Mail from Quincey summarizing shared data types:
+
+Quincey> Hi Robb,
+Quincey>     Everything looks good, I just have a couple of minor comments below:
+Quincey> 
+Quincey> > A very quick data types summary (so I can remember it next week :-)
+Quincey> > 
+Quincey> >    * Handles to named types are immutable.
+Quincey> > 
+Quincey> >    * A transient type handle can be converted to a named type handle
+Quincey> >      by calling H5Tcommit().  This can only be called for transient
+Quincey> >      types which are not locked or predefined.
+Quincey> > 
+Quincey> >    * H5Topen() returns a handle to a named immutable type.
+Quincey> > 
+Quincey> >    * H5Tcopy() returns a handle to a transient type.
+Quincey>     H5Tcreate also returns a handle to a transient type.
+Quincey> 
+Quincey> >    * Using a named type in H5Dcreate() causes the dataset object
+Quincey> >      header to point to the named type (shared).  The link count on
+Quincey> >      the named type is incremented.
+Quincey> > 
+Quincey> >    * Using a transient type in H5Dcreate() causes the type to be
+Quincey> >      copied and stored in the dataset header (unshared).
+Quincey> > 
+Quincey> >    * Type handles returned from H5Dget_type() are immutable.
+Quincey> > 
+Quincey> >    * If the dataset is using a shared type (dataset object header
+Quincey> >      points to some other object header with a type message, e.g., a
+Quincey> >      named type) then H5Dget_type() returns a handle to that named
+Quincey> >      type.
+Quincey> > 
+Quincey> >    * If the dataset has a private type (data type is stored in the
+Quincey> >      dataset object header) then H5Dget_type() returns a handle to a
+Quincey> >      transient immutable type.
+Quincey> > 
+Quincey> >    * The name of a data type can be removed from a group, but unless
+Quincey> >      the reference count becomes zero the type continues to exist.
+Quincey> >      (Other objects work this way too).
+Quincey> > 
+Quincey> >    * H5Tcopy() applied to a dataset returns a transient, modifiable
+Quincey> >      copy of that dataset's data type.
+Quincey> > 
+Quincey> >    * H5Topen() applied to a dataset returns either a transient
+Quincey> >      immutable or named immutable data type depending on whether the
+Quincey> >      dataset has a shared data type.
+Quincey>     Hmm, do we want to allow this?  It makes a certain amount of sense, but
+Quincey> is a little unusual... :-)
+Quincey> 
+
+Elena, we decided not not to allow H5Topen() on a dataset.
+
+Quincey> 
+Quincey> >    * The H5Tshare() and H5Tis_shared() will be removed.  Data types
+Quincey> >      will not be stored in the global heap.  A new type of shared
+Quincey> >      message header will be added to the object headers that points to 
+Quincey> >      another object header instead of the global heap
+Quincey> 
+Quincey> >    * Still to discuss: Attributes on named data types?
+Quincey>     I think we should all them.
+Quincey> 
+
+Elena, attributes work for named data types just like they do for
+datasets.
+
+Quincey> 
+Quincey> >    * Still to discuss: compound types whose members point to other types.
+Quincey>     I like this concept a lot and this we should figure out a way to do it.
+Quincey> This allows the "is a" relationship to be used very nicely for named datatypes.
+Quincey> 
+Quincey> >    * Still to discuss: datasets that point to data types in other
+Quincey> >      files by symbolic link.
+Quincey>     Probably a good idea also, just ugly to implement.
+Quincey> 
+
+
+
+
+ + + + +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 29 June 1998 + + + diff --git a/doc/src/RM_H5Z.html b/doc/src/RM_H5Z.html new file mode 100644 index 0000000..a5ef92c --- /dev/null +++ b/doc/src/RM_H5Z.html @@ -0,0 +1,93 @@ + + +HDF5/H5Z Draft API Specification + + + + +
+

H5Z: Compression Interface

+
+ +

Compression API Functions

+ +This function enable the user to configure a new compression +method for the local environment. + + + +
+ +       +
    +   +
+
+ +

+HDF5 supports compression of raw data by compression methods +built into the library or defined by an application. +A compression method is associated with a dataset when the dataset is +created and is applied independently to each storage chunk of the dataset. +The dataset must use the H5D_CHUNKED storage layout. +

+The HDF5 library does not support compression for contiguous datasets +because of the difficulty of implementing random access for partial I/O. +Compact dataset compression is not supported because it would not produce +significant results. +

+See Compression in the +HDF5 User's Guide for further information. + +

+
+
Name: H5Zregister +
Signature: +
herr_t H5Zregister(H5Z_method_t method, + const char *name, + H5Z_func_tcfunc, + H5Z_func_t ufunc + ) +
Purpose: +
Registers new compression and uncompression functions for a + method specified by a method number. +
Description: +
H5Zregister registers new compression and uncompression + functions for a method specified by a method number, method. + name is used for debugging and may be the null pointer. + Either or both of cfunc (the compression function) and + ufunc (the uncompression method) may be null pointers. +

+ The statistics associated with a method number are not reset + by this function; they accumulate over the life of the library. +

Parameters: +
+
H5Z_method_t method +
Number specifying compression method. +
const char *name +
Name associated with the method number. +
H5Z_func_t cfunc +
Compression method. +
H5Z_func_t ufunc +
Uncompression method. +
+
Returns: +
Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +
+ + +
+ +
+Frank Baker +
+HDF5 Documentation + +
+Last modified: 8 July 1998 + + + -- cgit v0.12