From d0f0bc2296e05d62b553f22e7a389650a335b7a1 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Thu, 9 Oct 2003 11:56:04 -0500 Subject: [svn-r7585] Purpose: Alphabetic sort of RM function entries Additional and modified HTML coding to accomodate HTMLdoc and automated PDF generation Function index formatting Platforms tested: IE 5, Safari --- doc/html/RM_H5G.html | 1169 +++++++++++++++++++++++++------------------------- 1 file changed, 583 insertions(+), 586 deletions(-) diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html index 3c18948..416ae6e 100644 --- a/doc/html/RM_H5G.html +++ b/doc/html/RM_H5G.html @@ -25,6 +25,7 @@ HDF5/H5G API Specification +
@@ -60,8 +61,7 @@ And in this document, the -
-
+

H5G: Group Interface

@@ -101,59 +101,61 @@ of objects in an HDF5 file. -
Alphabetical Listing
+        +        +
-

+
The FORTRAN90 Interfaces: -
In general, each FORTRAN90 subroutine performs exactly the same task -as the corresponding C function. The links below go to the C function +as the corresponding C function. The links below (electronic versions only) go to the C function descriptions, which serve as general descriptions for both. A button, under Non-C API(s) at the end of the C function description, opens an external browser window displaying the FORTRAN90-specific information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them. - +
@@ -208,7 +210,44 @@ create or access function.

+ + + +

+
+
Name: H5Gclose +
Signature: +
herr_t H5Gclose(hid_t group_id) +
Purpose: +
Closes the specified group. +
Description: +
H5Gclose releases resources used by a group which was + opened by H5Gcreate or H5Gopen. + After closing a group, the group_id cannot be used again. +

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Parameters: +
+
hid_t loc_id +
IN: Group or file identifier. +
hsize_t idx +
IN: Transient index identifying object. +
+
Returns: +
Returns the type of the object if successful. + Otherwise returns a negative value. + + +
Name: H5Giterate @@ -629,43 +783,60 @@ create or access function. -->
- + +
-
Name: H5Gmove +
Name: H5Glink
Signature: -
herr_t H5Gmove(hid_t loc_id, - const char *src_name, - const char *dst_name +
herr_t H5Glink(hid_t loc_id, + H5G_link_t link_type, + const char *current_name, + const char *new_name )
Purpose: -
Renames an object within an HDF5 file. +
Creates a link of the specified type from new_name + to current_name.
Description: -
H5Gmove renames an object within an HDF5 file. - The original name, src_name, is unlinked from the - group graph and the new name, dst_name, is inserted - as an atomic operation. Both names are interpreted relative - to loc_id, which is either a file or a group - identifier. -
Warning: -
Exercise care in moving groups as it is possible to render data in - a file inaccessible with H5Gmove. - See The Group Interface - in the HDF5 User's Guide. +
H5Glink creates a new name for an object that has some current + name, possibly one of many names it currently has. +

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

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

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

-

src_name and dst_name are interpreted relative to - src_name and dst_name, respectively, - which are either file or group identifiers. -
Warning: -
Exercise care in moving groups as it is possible to render data in a file - inaccessible with H5Gmove. See The - Group Interface in the HDF5 User's Guide. -
Parameters: +
Name: H5Glink2 +
Signature: + +
herr_t H5Glink2( + hid_t curr_loc_id, const char *current_name, + H5G_link_t link_type, + hid_t new_loc_id, const char *new_name ) +
Purpose: +
Creates a link of the specified type from new_name + to current_name. +
Description: + +
H5Glink2 creates a new name for an object that has some current + name, possibly one of many names it currently has. +

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

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

Parameters:
-
hid_t src_loc_id -
IN: Original file or group identifier. -
const char *src_name -
IN: Object's original name. -
hid_t dst_loc_id -
IN: Destination file or group identifier. -
const char *dst_name -
IN: Object's new name. +
hid_t curr_loc_id +
IN: The file or group identifier for the original object. +
const char * current_name +
IN: Name of the existing object if link is a hard link. + Can be anything for the soft link. +
H5G_link_t link_type +
IN: Link type. + Possible values are H5G_LINK_HARD and + H5G_LINK_SOFT. +
hid_t new_loc_id +
IN: The file or group identifier for the new link. +
const char * new_name +
IN: New name for the object.
-
Returns: -
Returns a non-negative value if successful; otherwise returns a negative - value. -
Non-C API(s): -
- +
+
- + +
-
Name: H5Gget_objinfo +
Name: H5Gmove
Signature: -
herr_t H5Gget_objinfo(hid_t loc_id, - const char *name, - hbool_t follow_link, - H5G_stat_t *statbuf +
herr_t H5Gmove(hid_t loc_id, + const char *src_name, + const char *dst_name )
Purpose: -
Returns information about an object. +
Renames an object within an HDF5 file.
Description: -
H5Gget_objinfo returns information about the - specified object through the statbuf argument. - loc_id (a file or group identifier) and - name together determine the object. - If the object is a symbolic link and follow_link is - zero (0), then the information returned is that for the link itself; - otherwise the link is followed and information is returned about - the object to which the link points. - If follow_link is non-zero but the final symbolic link - is dangling (does not point to anything), then an error is returned. - The statbuf fields are undefined for an error. - The existence of an object can be tested by calling this function - with a null statbuf. -

- H5Gget_objinfo fills in the following data structure: - 

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

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

Note: -
Some systems will be able to record the time accurately but - unable to retrieve the correct time; such systems (e.g., Irix64) - will report an mtime value of 0 (zero). +
H5Gmove renames an object within an HDF5 file. + The original name, src_name, is unlinked from the + group graph and the new name, dst_name, is inserted + as an atomic operation. Both names are interpreted relative + to loc_id, which is either a file or a group + identifier. +
Warning: +
Exercise care in moving groups as it is possible to render data in + a file inaccessible with H5Gmove. + See The Group Interface + in the HDF5 User's Guide.
Parameters:
hid_t loc_id
IN: File or group identifier. -
const char *name -
IN: Name of the object for which status is being sought. -
hbool_t follow_link -
IN: Link flag. -
H5G_stat_t *statbuf -
OUT: Buffer in which to return information about the object. +
const char *src_name +
IN: Object's original name. +
const char *dst_name +
IN: Object's new name.
Returns: -
Returns a non-negative value if successful, with the fields of - statbuf (if non-null) initialized. - Otherwise returns a negative value. - - -
- - - - - - - - - - -
-
-
Name: H5Gget_num_objs -
Signature: -
herr_t H5Gget_num_objs(hid_t loc_id, - hsize_t* num_obj) -
Purpose: -
Returns number of objects in the group specified by its identifier -
Description: -
H5Gget_num_objs returns number of objects in a group. - Group is specified by its identifier loc_id. - If a file identifier is passed in, then the number of objects in the - root group is returned. -
Parameters: -
-
hid_t loc_id -
IN: Identifier of the group or the file -
hsize_t* num_obj -
OUT: Number of objects in the group. -
-
Returns: -
Returns positive value if successful; - otherwise returns a negative value. -
- - - - -
-
-
Name: H5Gget_objname_by_idx -
Signature: -
ssize_t H5Gget_objname_by_idx(hid_t loc_id, - hsize_t idx, - char *name, - size_t* size ) -
Purpose: -
Returns a name of an object specified by an index. -
Description: -
H5Gget_objname_by_idx returns a name of the object - specified by the index idx in the group loc_id. -

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

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

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

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

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

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

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

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

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

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

+

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

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

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

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

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

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

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

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

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

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

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

Warning: +
Exercise care in unlinking groups as it is possible to render data in + a file inaccessible with H5Gunlink. + See The Group Interface + in the HDF5 User's Guide.
Parameters:
hid_t loc_id -
IN: Identifier of the file or group. -
const char *name -
IN: Name of the object whose comment is to be set or reset. -
size_t bufsize -
IN: Anticipated size of the buffer required to hold - comment. -
char *comment -
OUT: The comment. +
IN: Identifier of the file or group containing the object. +
const char * name +
IN: Name of the object to unlink.
Returns: -
Returns the number of characters in the comment, - counting the null terminator, if successful; the value - returned may be larger than bufsize. - Otherwise returns a negative value. +
Returns a non-negative value if successful; + otherwise returns a negative value.
Non-C API(s): -
-
@@ -1183,14 +1179,15 @@ And in this document, the
-
-
+
HDF Help Desk
Describes HDF5 Release 1.6.0, July 2003 -
- -Last modified: 26 August 2003 +
-- cgit v0.12