From 26cd535ff23e4f6f440a4aa28e409f474ef92f66 Mon Sep 17 00:00:00 2001
From: Frank Baker Generic Properties
+ File Creation Properties
+ Zero-sized properties are allowed and do not store any data in the
+ property list. These may be used as flags to indicate the presence
+ or absence of a particular piece of information. The default pointer
+ for a zero-sized property may be set to NULL.
+ The property
+
+
-
-
-
-
-
-
-
-|| Indicates functions
- available only in the
- parallel HDF5 library.
+
- File Access Properties
+
+ File Close Properties
+
+
+ File Access Properties
+
+
+
+
+
+|| Indicates functions
+ available only in the
+ parallel HDF5 library.
+
+
+
+
+
+H5Pcreate_list
(
+ hid_t class
)
+
+ H5Pcreate_list
creates a new property list of a
+ given class. If a create
callback exists for the
+ property list class, it is called before the property list
+ is passed back to the user.
+ If create
callbacks exist for any individual properties
+ in the property list, they are called before the class
+ create
callback.
+
+
+
+
+
+
+ hid_t
+ class
;IN: Class of property list to create.
+
+
H5Pregister
(
+ hid_t class
,
+ const char * name
,
+ size_t size
,
+ void * default
,
+ H5P_prp_create_func_t create
,
+ H5P_prp_set_func_t set
,
+ H5P_prp_get_func_t get
,
+ H5P_prp_delete_func_t delete
,
+ H5P_prp_copy_func_t copy
,
+ H5P_prp_close_func_t close
+ )
+
+ H5Pregister
registers a new property with a
+ property list class.
+ The property will exist in all property list objects of
+ class
created after this routine finishes. The name
+ of the property must not already exist, or this routine will fail.
+ The default property value must be provided and all new property
+ lists created with this property will have the property value set
+ to the default value. Any of the callback routines may be set to
+ NULL if they are not needed.
+
+ create
and close
callbacks
+ are called for zero-sized properties, but the set
and
+ get
callbacks are never called.
+ create
routine is called when a new property list
+ with this property is being created.
+ The H5P_prp_create_func_t
callback function is defined
+ as follows:
+ typedef herr_t (*
+ The parameters to this callback function are defined as follows:
+ H5P_prp_create_func_t
)(
+ const char *name
,
+ size_t size
,
+ void *initial_value
);
+
+ The
+
+
+ const char *
+ name
IN: The name of the property being modified
+
+ size_t
+ size
IN: The size of the property in bytes
+
+ void *
+ initial_value
IN/OUT: The default value for the property being created,
+ which will be passed to H5Pregister
create
routine may modify the value to be set and
+ those changes will be stored as the initial value of the property.
+ If the create
routine returns a negative value,
+ the new property value is not copied into the property and the
+ create routine returns an error value.
+
set
routine is called before a new value is copied
+ into the property.
+ The H5P_prp_set_func_t
callback function is defined
+ as follows:
+ prop_id
,
+ const char *name
,
+ size_t size
,
+ void *new_value
);
+ hid_t prop_id |
+ IN: The identifier of the property list being modified |
const char *name |
+ IN: The name of the property being modified |
size_t size |
+ IN: The size of the property in bytes |
void **new_value |
+ IN/OUT: Pointer to new value pointer for the property being + modified |
set
routine may modify the value pointer to be set
+ and those changes will be used when setting the property's value.
+ If the set
routine returns a negative value, the new
+ property value is not copied into the property and the
+ set
routine returns an error value.
+ The set
routine will not be called for the initial
+ value, only the create
routine will be called.
+
+
+ The get
routine is called when a value is retrieved
+ from a property value.
+ The H5P_prp_get_func_t
callback function is defined
+ as follows:
+ H5P_prp_get_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ hid_t prop_id |
+ IN: The identifier of the property list being queried |
const char * name |
+ IN: The name of the property being queried |
size_t size |
+ IN: The size of the property in bytes |
void * value |
+ IN/OUT: The value of the property being returned |
get
routine may modify the value to be returned from
+ the query and those changes will be returned to the calling routine.
+ If the set
routine returns a negative value, the query
+ routine returns an error value.
+
+
+ The delete
routine is called when a property is being
+ deleted from a property list.
+ The H5P_prp_delete_func_t
callback function is defined
+ as follows:
+ H5P_prp_delete_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ hid_t prop_id |
+ IN: The identifier of the property list the property is being + deleted from |
const char * name |
+ IN: The name of the property in the list |
size_t size |
+ IN: The size of the property in bytes |
void * value |
+ IN: The value for the property being deleted |
delete
routine may modify the value passed in,
+ but the value is not used by the library when the delete
+ routine returns. If the delete
routine returns
+ a negative value, the property list delete routine returns
+ an error value but the property is still deleted.
+
+
+ The copy
routine is called when a new property list with
+ this property is being created through a copy operation.
+ The H5P_prp_copy_func_t
callback function is defined
+ as follows:
+ H5P_prp_copy_func_t
)(
+ const char *name
,
+ size_t size
,
+ void *value
);
+ const char *name |
+ IN: The name of the property being copied |
size_t size |
+ IN: The size of the property in bytes |
void *value |
+ IN/OUT: The value for the property being copied |
copy
routine may modify the value to be set and
+ those changes will be stored as the new value of the property.
+ If the copy
routine returns a negative value,
+ the new property value is not copied into the property and
+ the copy routine returns an error value.
+
+
+ The close
routine is called when a property list with
+ this property is being closed.
+ The H5P_prp_close_func_t
callback function is defined
+ as follows:
+ H5P_prp_close_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ hid_t prop_id |
+ IN: The identifier of the property list being + closed |
const char *name |
+ IN: The name of the property in the list |
size_t size |
+ IN: The size of the property in bytes |
void *value |
+ IN: The value for the property being closed |
close
routine may modify the value passed in,
+ but the value is not used by the library when the
+ close
routine returns.
+ If the close
routine returns a negative value,
+ the property list close routine returns an error value but
+ the property list is still closed.
+ hid_t class |
+ IN: Property list class to register permanent property + within |
const char * name |
+ IN: Name of property to register |
size_t size |
+ IN: Size of property in bytes |
void * default |
+ IN: Default value for property in newly created property + lists |
H5P_prp_create_func_t create |
+ IN: Callback routine called when a property list is being + created and the property value will be initialized |
H5P_prp_set_func_t set |
+ IN: Callback routine called before a new value is copied + into the property's value |
H5P_prp_get_func_t get |
+ IN: Callback routine called when a property value is + retrieved from the property |
H5P_prp_delete_func_t delete |
+ IN: Callback routine called when a property is deleted from + a property list |
H5P_prp_copy_func_t copy |
+ IN: Callback routine called when a property is copied from + a property list |
H5P_prp_close_func_t close |
+ IN: Callback routine called when a property list is being + closed and the property value will be disposed of |
set
callback function may be useful to range check the value being
+ set for the property or may perform some tranformation/translation of the
+ value set. The get
callback would then [probably] reverse the
+ transformation, etc. A single get
or set
callback could
+ handle multiple properties by performing different actions based on the
+ property name or other properties in the property list.
+
+ I would like to say "the property list is not closed" when a close
+ routine fails, but I don't think that's possible due to other properties in
+ the list being successfully closed and removed from the property list. I
+ suppose that it would be possible to just remove the properties which have
+ successful close
callbacks, but I'm not happy with the ramifications
+ of a mangled, un-closable property list hanging around... Any comments?
+
+
+
+
H5Pinsert
(
+ hid_t plid
,
+ const char *name
,
+ size_t size
,
+ void *value
,
+ H5P_prp_set_func_t set
,
+ H5P_prp_get_func_t get
,
+ H5P_prp_delete_func_t delete
,
+ H5P_prp_copy_func_t copy
,
+ H5P_prp_close_func_t close
+ )
+
+ H5Pinsert
create a new property in a property list.
+ The property will exist only in this property list and copies made
+ from it.
+
+
+ The initial property value must be provided in
+ value
and the property value will be set accordingly.
+
+
+ The name of the property must not already exist in this list, + or this routine will fail. + +
+ The set
and get
callback routines may
+ be set to NULL if they are not needed.
+
+
+ Zero-sized properties are allowed and do not store any data in the + property list. The default value of a zero-size property may be set + to NULL. They may be used to indicate the presence or absence of a + particular piece of information. +
+ + Theset
routine is called before a new value is copied
+ into the property.
+ The H5P_prp_set_func_t
calback function is defined
+ as follows:
+ H5P_prp_set_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *new_value
);
+ hid_t prop_id |
+ IN: The identifier of the property list being modified |
const char *name |
+ IN: The name of the property being modified |
size_t size |
+ IN: The size of the property in bytes |
void **new_value |
+ IN: Pointer to new value pointer for the property being + modified |
set
routine may modify the value pointer to be set
+ and those changes will be used when setting the property's value.
+ If the set
routine returns a negative value, the new
+ property value is not copied into the property and the set routine
+ returns an error value.
+ The set
routine will be called for the initial value.
+
+
+ The get
routine is called when a value is retrieved
+ from a property value.
+ The H5P_prp_get_func_t
callback functioin is defined
+ as follows:
+ H5P_prp_get_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ hid_t prop_id |
+ IN: The identifier of the property list being queried |
const char * |
+ IN: The name of the property being queried |
size_t size |
+ IN: The size of the property in bytes |
void *value |
+ IN: The value of the property being returned |
get
routine may modify the value to be returned from
+ the query and those changes will be preserved.
+ If the get
routine returns a negative value, the query
+ routine returns an error value.
+
+
+ The delete
routine is called when a property is being
+ deleted from a property list.
+ The H5P_prp_delete_func_t
callback function is defined
+ as follows:
+ typedef herr_t
(*H5P_prp_delete_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ hid_t prop_id |
+ IN: The identifier of the property list the property is + being deleted from |
const char * name |
+ IN: The name of the property in the list |
size_t size |
+ IN: The size of the property in bytes |
void * value |
+ IN: The value for the property being deleted |
delete
routine may modify the value passed in,
+ but the value is not used by the library when the delete
+ routine returns. If the delete
routine returns a
+ negative value, the property list delete routine returns an
+ error value but the property is still deleted.
+
+
+ The copy
routine is called when a new property list
+ with this property is being created through a copy operation.
+ The H5P_prp_copy_func_t
collback function is defined
+ as follows:
+ H5P_prp_copy_func_t
)(
+ const char *name
,
+ size_t size
,
+ void *value
);
+ const char *name |
+ IN: The name of the property being copied |
size_t size |
+ IN: The size of the property in bytes |
void * value |
+ IN/OUT: The value for the property being copied |
copy
routine may modify the value to be set and
+ those changes will be stored as the new value of the property.
+ If the copy
routine returns a negative value, the
+ new property value is not copied into the property and the
+ copy routine returns an error value.
+
+ The close
routine is called when a property list
+ with this property is being closed.
+ The H5P_prp_close_func_t
callback function is defined
+ as follows:
+
H5P_prp_close_func_t
)(
+ hid_t prop_id
,
+ const char *name
,
+ size_t size
,
+ void *value
);
+ hid_t |
+ IN: The ID of the property list being closed |
const char * name |
+ IN: The name of the property in the list |
size_t size |
+ IN: The size of the property in bytes |
void * value |
+ IN: The value for the property being closed |
close
routine may modify the value passed in, the value
+ is not used by the library when the close
routine returns.
+ If the close
routine returns a negative value, the
+ property list close routine returns an error value but the property list
+ is still closed.
+
+ hid_t plid |
+ IN: Property list identifier to create temporary property + within |
const char *name |
+ IN: Name of property to create |
size_t size |
+ IN: Size of property in bytes |
void *value |
+ IN: Initial value for the property |
H5P_prp_set_func_t set |
+ IN: Callback routine called before a new value is copied into + the property's value |
H5P_prp_get_func_t get |
+ IN: Callback routine called when a property value is retrieved + from the property |
H5P_prp_delete_func_t delete |
+ IN: Callback routine called when a property is deleted from + a property list |
H5P_prp_copy_func_t copy |
+ IN: Callback routine called when a property is copied from + an existing property list |
H5P_prp_close_func_t close |
+ IN: Callback routine called when a property list is being closed + and the property value will be disposed of |
set
callback function may be useful to range check
+ the value being set for the property or may perform some
+ tranformation/translation of the value set. The get
callback
+ would then [probably] reverse the transformation, etc. A single
+ get
or set
callback could handle
+ multiple properties by performing different actions based on the
+ property name or other properties in the property list.
+
+
+ There is no create
callback routine for temporary property
+ list objects, the initial value is assumed to have any necessary setup
+ already performed on it.
+
+
+ I would like to say "the property list is not closed" when a close
+ routine fails, but I don't think that's possible due to other properties in
+ the list being successfully closed and removed from the property list. I
+ suppose that it would be possible to just remove the properties which have
+ successful close
callbacks, but I'm not happy with the
+ ramifications of a mangled, un-closable property list hanging around...
+ Any comments?
+
H5Pset
(
+ hid_t plid
,
+ const char *name
,
+ void *value
)
+ )
+
+ H5Pset
sets a new value for a property in a
+ property list. If there is a set
callback
+ routine registered for this property, the value
will be
+ passed to that routine and any changes to the value
+ will be used when setting the property value.
+ The information pointed to by the value
pointer
+ (possibly modified by the set
callback) is copied into
+ the property list value and may be changed by the application making
+ the H5Pset
call without affecting the property value.
+
+ + The property name must exist or this routine will fail. + +
+ If the set
callback routine returns an error, the
+ property value will not be modified.
+
+
+ This routine may not be called for zero-sized properties + and will return an error in that case. + +
hid_t plid ;
+ | IN: Property list identifier to modify |
const char *name ;
+ | IN: Name of property to modify |
void *value ;
+ | IN: Pointer to value to set the property to |
H5Pexist
(
+ hid_t id
;
+ const char *name
+ )
+
+ H5Pexist
determines whether a property exists
+ within a property list or class.
+
+ hid_t id |
+ IN: Identifier for the property to query |
const char *name |
+ IN: Name of property to check for |
H5Pget_size
(
+ hid_t id
,
+ const char *name
,
+ size_t *size
+ )
+
+ H5Pget_size
retrieves the size of a
+ property's value in bytes. This function operates on both
+ poperty lists and property classes
+
+
+ Zero-sized properties are allowed and return 0
.
+
+
+
hid_t id |
+ IN: Identifier of property object to query |
const char *name |
+ IN: Name of property to query |
size_t *size |
+ OUT: Size of property in bytes |
H5Pget_nprops
(
+ hid_t id
,
+ size_t *nprops
+ )
+
+ H5Pget_nprops
retrieves the number of properties in a
+ property list or class.
+ If a property class identifier is given, the number of registered
+ properties in the class is returned in nprops
.
+ If a property list identifier is given, the current number of
+ properties in the list is returned in nprops
.
+
+ hid_t id |
+ IN: Identifier of property object to query |
size_t *nprops |
+ OUT: Number of properties in object |
H5Pget_class_name
(
+ hid_t pcid
+ )
+
+ H5Pget_class_name
retrieves the name of a
+ generic property list class. The pointer to the name
+ must be freed by the user after each successful call.
+
+ hid_t pcid |
+ IN: Identifier of the property class to query |
H5Pget_class_parent
(
+ hid_t pcid
+ )
+
+ hid_t pcid |
+ IN: Identifier of the property class to query |
H5Pget_class_parent
retrieves an identifier for the
+ parent class of a property class.
+
+
+
+H5Pisa_class
(
+ hid_t plist
,
+ hid_t pclass
+ )
+
+ H5Pisa_class
checks to determine whether a property list
+ is a member of the specified class.
+
+ hid_t plist |
+ IN: Identifier of the property list |
hid_t pclass |
+ IN: Identifier of the property class |
H5Pget
(
+ hid_t plid
,
+ const char *name
,
+ void *value
+ )
+
+ H5Pget
retrieves a copy of the value for a property
+ in a property list. If there is a get
callback routine
+ registered for this property, the copy of the value of the property
+ will first be passed to that routine and any changes to the copy of
+ the value will be used when returning the property value from this
+ routine.
+
+
+ This routine may be called for zero-sized properties with the
+ value
set to NULL. The get
routine
+ will be called with a NULL value if the callback exists.
+
+
+ The property name must exist or this routine will fail. + +
+ If the get
callback routine returns an error,
+ value
will not be modified.
+
+
hid_t plid |
+ IN: Identifier of the property list to query |
const char *name |
+ IN: Name of property to query |
void *value |
+ OUT: Pointer to a location to which to copy the value of + of the property |
H5Pequal
(
+ hid_t id1,
+ hid_t id2
+ )
+
+ H5Pequal
compares two property lists or classes
+ to determine whether they are equal to one another.
+
+
+ Either both id1
and id2
must be
+ property lists or both must be classes; comparing a list to a
+ class is an error.
+
+
hid_t id1 |
+ IN: First property object to be compared |
hid_t id2 |
+ IN: Second property object to be compared |
H5Piterate
(
+ hid_t id
,
+ int * idx
,
+ H5P_iterate_t iter_func
,
+ void * iter_data
+ )
+
+ H5Piterate
iterates over the properties in the
+ property object specified in id
, which may be either a
+ property list or a property class, performing a specified
+ operation on each property in turn.
+
+
+ For each property in the object, iter_func
and
+ the additional information specified below are passed to the
+ H5P_iterate_t
operator function.
+
+ (NOTE: iter_func
was changed to
+ H5P_iterate_t
in the preceding sentence.
+ Is this correct?)
+
+
+ The iteration begins with the idx
-th property in
+ the object; the next element to be processed by the operator
+ is returned in idx
.
+ If idx
is NULL, the iterator starts at the first
+ property; since no stopping point is returned in this case,
+ the iterator cannot be restarted if one of the calls to its
+ operator returns non-zero.
+
H5P_iterate_t
operator is
+ as follows:
+ H5P_iterate_t
)(
+ hid_t id
,
+ const char *>name
,
+ void *iter_data
+ )
+ id
,
+ the name of the current property within the object, name
,
+ and the pointer to the operator data passed in to
+ H5Piterate
, iter_data
.
+
+
+ The valid return values from an operator are as follows:
+ Zero | +Causes the iterator to continue, returning zero when all + properties have been processed |
Positive | +Causes the iterator to immediately return that positive + value, indicating short-circuit success. The iterator can + be restarted at the index of the next property |
Negative | +Causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the + index of the next property |
+ H5Piterate
assumes that the properties in the object
+ identified by id
remain unchanged through the iteration.
+ If the membership changes during the iteration, the function's behavior
+ is undefined.
+
+
hid_t id |
+ IN: Identifier of property object to iterate over |
int * idx |
+ IN/OUT: Index of the property to begin with |
H5P_iterate_t iter_func |
+ IN: Function pointer to function to be called with each + property iterated over |
void * iter_data |
+ IN/OUT: Pointer to iteration data from user |
iter_func
if it was non-zero;
+ zero if all properties have been processed
+ H5Pcopy_prop
(
+ hid_t dst_id
,
+ hid_t src_id
,
+ const char *name
+ )
+
+ H5Pcopy_prop
copies a property from one property
+ list or class to another.
+
+ + If a property is copied from one class to another, all the property + information will be first deleted from the destination class and + then the property information will be copied from the source class + into the destination class. + +
+ If a property is copied from one list to another, the property
+ will be first deleted from the destination list (generating a call
+ to the close
callback for the property, if one exists)
+ and then the property is copied from the source list to the
+ destination list (generating a call to the copy
+ callback for the property, if one exists).
+
+
+ If the property does not exist in the class or list, this call is
+ equivalent to calling H5Pregister
or H5Pinsert
+ (for a class or list, as appropriate) and the create
+ callback will be called in the case of the property being
+ copied into a list (if such a callback exists for the property).
+
+
hid_t dst_id |
+ IN: Identifier of the destination property list or + class |
hid_t src_id |
+ IN: Identifier of the source property list or class |
const char *name |
+ IN: Name of the property to copy |
H5Premove
(plid, name
)
+ hid_t plid
;
+ const char *name
+ )
+
+ H5Premove
removes a property from a property list.
+
+
+ Both properties which were in existence when the property list
+ was created (i.e. properties registered with H5Pregister
)
+ and properties added to the list after it was created (i.e. added
+ with H5Pinsert
) may be removed from a property list.
+ Properties do not need to be removed from a property list before the
+ list itself is closed; they will be released automatically when
+ H5Pclose
is called.
+
+
+ If a close
callback exists for the removed property,
+ it will be called before the property is released.
+
+
hid_t plid |
+ IN: Identifier of the property list to modify |
const char *name |
+ IN: Name of property to remove |
H5Punregister
(
+ H5P_class_t class
,
+ const char *name
+ )
+
+ H5Punregister
removes a property from a
+ property list class.
+
+ + Future property lists created of that class will not contain + this property; + existing property lists containing this property are not affected. + +
H5P_class_t class |
+ IN: Property list class from which to remove + permanent property |
const char *name |
+ IN: Name of property to remove |
H5Pclose_list
(
+ hid_t plist
+ )
+
+ H5Pclose_list
closes a property list.
+
+
+ If a close
callback exists for the property list class,
+ it is called before the property list is destroyed.
+ If close
callbacks exist for any individual properties
+ in the property list, they are called after the class
+ close
callback.
+
+
hid_t plist | + | IN: Property list to close |
H5Pclose_class
(
+ hid_t class
+ )
+
+ + Existing property lists of this class will continue to exist, + but new ones are not able to be created. + +
hid_t class |
+ IN: Property list class to close |
H5Pget_version
(hid_t plist
,
@@ -3974,6 +5577,119 @@ fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl);
H5Pset_fclose_degree
(hid_t fapl_id
,
+ H5F_close_degree_t fc_degree
)
+ H5Pset_fclose_degree
sets the file close degree property fc_degree
+ in the file access property list fapl_id
.
+ The value of fc_degree
determines how aggressively H5Fclose
+ deals with objects within a file that remain open when H5Fclose
+ is called to close that file. fc_degree
can have any one of
+ four valid values:
+
Degree name | +H5Fclose behavior with no open object
+ in file |
+ H5Fclose behavior with open object(s)
+ in file |
+
---|---|---|
H5F_CLOSE_WEAK |
+ Actual file is closed. | +Access to file identifier is terminated; actual file + close is delayed until all objects in file are closed | +
H5F_CLOSE_SEMI |
+ Actual file is closed. | +Function returns FAILURE | +
H5F_CLOSE_STRONG |
+ Actual file is closed. | +All open objects ramaining in the file are closed then + file is closed | +
H5F_CLOSE_DEFAULT |
+ The VFL driver chooses the behavior. Currently,
+ all VFL drivers set this value to H5F_CLOSE_WEAK , except
+ for the MPI-I/O driver, which sets it to H5F_CLOSE_SEMI .
+ |
+
fapl_id
+ fc_degree
+ fc_degree
.
+ H5Pget_fclose_degree
(hid_t fapl_id
,
+ H5F_close_degree_t fc_degree
)
+ H5Pget_fclose_degree
returns the current setting of the file
+ close degree property fc_degree
in the file access property list
+ fapl_id
.
+ The value of fc_degree
determines how aggressively H5Fclose
+ deals with objects within a file that remain open when H5Fclose
+ is called to close that file. fc_degree
can have any one of
+ four valid values as described above in H5Pset_fclose_degree
.
+
fapl_id
+ fc_degree
+ fc_degree
.
+