From 6a9e054486a4d611bc9e25e3ab3c89fc658ed3b8 Mon Sep 17 00:00:00 2001
From: Frank Baker <fbaker@hdfgroup.org>
Date: Tue, 24 Aug 2004 14:01:00 -0500
Subject: [svn-r9144] Purpose:     Add H5Fget_name     Add H5Fget_filesize    
 Minor correction in HTML coding of H5Fget_freespace Platforms tested:    
 Mozilla

---
 doc/html/RM_H5F.html | 145 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 140 insertions(+), 5 deletions(-)

diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html
index 71eb12a..93618bc 100644
--- a/doc/html/RM_H5F.html
+++ b/doc/html/RM_H5F.html
@@ -90,11 +90,13 @@ documented below.
     <li><a href="#File-Mount">H5Fmount</a>
     <li><a href="#File-Unmount">H5Funmount</a>
     <li><a href="#File-GetVfdHandle">H5Fget_vfd_handle</a>
-    <li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
+    <li><a href="#File-GetFilesize">H5Fget_filesize</a>
 </ul>
 </td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
 <ul>
+    <li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
     <li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
+    <li><a href="#File-GetName">H5Fget_name</a>
     <li><a href="#File-GetObjCount">H5Fget_obj_count</a>
     <li><a href="#File-GetObjIDs">H5Fget_obj_ids</a>
     <li><a href="#File-GetFreeSpace">H5Fget_freespace</a>
@@ -114,6 +116,7 @@ documented below.
       <li><a href="#File-Flush">H5Fflush</a>
       <li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
       <li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
+      <li><a href="#File-GetFilesize">H5Fget_filesize</a>
     </ul>      
     </td>
     
@@ -122,10 +125,10 @@ documented below.
     <td valign="top">
 	<ul>
       <li><a href="#File-GetFreeSpace">H5Fget_freespace</a>
+      <li><a href="#File-GetName">H5Fget_name</a>
       <li><a href="#File-GetObjCount">H5Fget_obj_count</a>
       <li><a href="#File-GetObjIDs">H5Fget_obj_ids</a>
       <li><a href="#File-GetVfdHandle">H5Fget_vfd_handle</a>
-      <li><a href="#File-IsHDF5">H5Fis_hdf5</a>
 	</ul>
     </td>
     
@@ -133,6 +136,7 @@ documented below.
     
     <td valign="top">
 	<ul>
+      <li><a href="#File-IsHDF5">H5Fis_hdf5</a>
       <li><a href="#File-Mount">H5Fmount</a>
       <li><a href="#File-Open">H5Fopen</a>
       <li><a href="#File-Reopen">H5Freopen</a>
@@ -164,11 +168,13 @@ as the corresponding C function.
     <li><a href="#File-Mount">h5fmount_f</a>
     <li><a href="#File-Unmount">h5funmount_f</a>
     <li><a href="#File-GetVfdHandle">h5fget_vfd_handle_f</a>
-    <li><a href="#File-GetCreatePlist">h5fget_create_plist_f</a>
+    <li><a href="#File-GetFilesize">h5fget_filesize_f</a>
 </ul>
 </td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
 <ul>
+    <li><a href="#File-GetCreatePlist">h5fget_create_plist_f</a>
     <li><a href="#File-GetAccessPlist">h5fget_access_plist_f</a>
+    <li><a href="#File-GetName">h5fget_name_f</a>
     <li><a href="#File-GetObjCount">h5fget_obj_count_f</a>
     <li><a href="#File-GetObjIDs">h5fget_obj_ids_f</a>
     <li><a href="#File-GetObjIDs">h5fget_freespace_f</a>
@@ -508,6 +514,7 @@ END SUBROUTINE h5fget_access_plist_f
         -->
 </dl>
 
+
 <!-- NEW PAGE -->
 <!-- HEADER RIGHT "H5Fget_create_plist" -->
 <hr>
@@ -563,10 +570,63 @@ END SUBROUTINE h5fget_create_plist_f
 
 
 <!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Fget_filesize" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="File-GetFilesize">H5Fget_filesize</a>
+<dt><strong>Signature:</strong>
+    <dd><em>herr_t </em><code>H5Fget_filesize</code>(<em>hid_t</em> <code>file_id</code>,
+                        <em>hsize_t *</em><code>size</code>
+        )
+<dt><strong>Purpose:</strong>
+        <dd>Returns the size of an HDF5 file.
+<dt><strong>Description:</strong>
+    <dd><code>H5Fget_filesize</code> returns the size
+        of the HDF5 file specified by <code>file_id</code>.
+        <p>
+        The returned size is that of the entire file, 
+        as opposed to only the HDF5 portion of the file.
+        I.e., <code>size</code> includes the user block, if any, 
+        the HDF5 portion of the file, and
+        any data that may have been appended 
+        beyond the data written through the HDF5 Library.
+<dt><strong>Parameters:</strong>
+    <dl>
+        <dt><em>hid_t</em> <code>file_id</code>
+            <dd>IN: Identifier of a currently-open HDF5 file
+        <dt><em>hsize_t *</em><code>size</code>
+            <dd>OUT: Size of the file, in bytes.
+    </dl>
+<dt><strong>Returns:</strong>
+    <dd>Returns a non-negative value if successful;
+        otherwise returns a negative value.
+<dt><strong>Fortran90 Interface:</strong> h5fget_freespace_f
+    <dd>
+	<pre>
+SUBROUTINE h5fget_filesize_f(file_id, size, hdferr)
+
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(IN) :: file_id    ! file identifier
+  INTEGER(HSIZE_T), INTENT(OUT) :: size    ! Size of the file 
+  INTEGER, INTENT(OUT) :: hdferr           ! Error code: 0 on success,
+                                           ! -1 if fail
+END SUBROUTINE h5fget_filesize_f 
+	</pre>		
+		
+		<!--<dt><strong>Non-C API(s):</strong>
+    	<dd>
+        
+        <img src="Graphics/Java.gif"> 
+        <img src="Graphics/C++.gif">
+        -->
+</dl>
+
+
+<!-- NEW PAGE -->
 <!-- HEADER RIGHT "H5Fget_freespace" -->
 <hr>
 <dl>
-<dt><strong>Name:</strong> <a name="File-GetFreeSpace">H5Fget_freespace</a>
+<dt><strong>Name:</strong> <a name="File-GetFreespace">H5Fget_freespace</a>
 <dt><strong>Signature:</strong>
     <dd><em>hssize_t </em><code>H5Fget_freespace</code>(<em>hid_t</em> <code>file_id</code>)
 <dt><strong>Purpose:</strong>
@@ -612,6 +672,81 @@ END SUBROUTINE h5fget_freespace_f
         -->
 </dl>
 
+
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Fget_name" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="File-GetName">H5Fget_name</a>
+<dt><strong>Signature:</strong>
+    <dd><em>ssize_t</em> <code>H5Fget_name</code>(<em>hid_t</em> <code>obj_id</code>,
+                     <em>char *</em><code>name</code>,
+                     <em>size_t</em> <code>size</code>
+        )
+
+<dt><strong>Purpose:</strong>
+        <dd>Retrieves name of file to which object belongs.
+<dt><strong>Description:</strong>
+        <dd><code>H5Fget_name</code> retrieves the name of the file 
+	    to which the object <code>obj_id</code> belongs.
+	    The object can be a group, dataset, attribute, or 
+	    named datatype.
+            <p> 
+	    Up to <code>size</code> characters of the filename 
+	    are returned in <code>name</code>; 
+	    additional characters, if any, are not returned to 
+	    the user application. 
+            <p>
+	    If the length of the name, 
+	    which determines the required value of <code>size</code>, 
+	    is unknown, a preliminary <code>H5Fget_name</code> call 
+	    can be made by setting <code>name</code> to NULL. 
+	    The return value of this call will be the size of the filename;
+	    that value can then be assigned to <code>size</code> 
+	    for a second <code>H5Fget_name</code> call, 
+	    which will retrieve the actual name. 
+            <p>
+            If an error occurs, the buffer pointed to by 
+	    <code>name</code> is unchanged and 
+	    the function returns a negative value.
+<dt><strong>Parameters:</strong>
+    <dl>
+        <dt><em>hid_t</em> <code>obj_id</code>
+            <dd>IN: Identifier of the object for which the 
+	        associated filename is sought.
+	        The object can be a group, dataset, attribute, or 
+	        named datatype.
+        <dt><em>char *</em><code>name</code>
+            <dd>OUT: Buffer to contain the returned filename.
+        <dt><em>size_t</em> <code>size</code>
+            <dd>IN: Size, in bytes, of the <code>name</code> buffer.
+    </dl>
+<dt><strong>Returns:</strong>
+    <dd>Returns the length of the filename if successful;
+        otherwise returns a negative value.
+<dt><strong>Fortran90 Interface:</strong> h5fget_name_f
+    <dd>
+	<pre>
+SUBROUTINE h5fget_name_f(obj_id, buf, size, hdferr)
+
+  IMPLICIT NONE
+  INTEGER(HID_T), INTENT(IN) :: obj_id     ! Object identifier 
+  CHARACTER(LEN=*), INTENT(INOUT) :: buf   ! Buffer to hold filename
+  INTEGER(SIZE_T), INTENT(OUT) :: size     ! Size of the filename
+  INTEGER, INTENT(OUT) :: hdferr           ! Error code: 0 on success,
+                                           ! -1 if fail
+END SUBROUTINE h5fget_name_f
+	</pre>		
+		
+		<!--<dt><strong>Non-C API(s):</strong>
+    	<dd>
+        
+        <img src="Graphics/Java.gif"> 
+        <img src="Graphics/C++.gif">
+        -->
+</dl>
+
+
 <!-- NEW PAGE -->
 <!-- HEADER RIGHT "H5Fget_obj_count" -->
 <hr>
@@ -1224,7 +1359,7 @@ And in this document, the
 Describes HDF5 Release 1.6.2, February 2004
 </address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
 <!--
-document.writeln("Last modified: 16 October 2003");
+document.writeln("Last modified: 24 August 2004");
 -->
 </SCRIPT>
  
-- 
cgit v0.12