<html>
<head><title>
HDF5/H5F Draft API Specification
</title></head>

<body>

<hr>
<center>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
H5F&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<a href="Tools.html">Tools</a>&nbsp;&nbsp;
<!--
<a href="Glossary.html">Glossary</a>
-->
</center>
<hr>

<center>
<h1>H5F: File Interface</h1>
</center>

<h2>File API Functions</h2>

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.

<table border=0>
<tr><td valign=top>
<ul>
    <li><a href="#File-Open">H5Fopen</a>
    <li><a href="#File-Create">H5Fcreate</a>
    <li><a href="#File-IsHDF5">H5Fis_hdf5</a>
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
    <li><a href="#File-Flush">H5Fflush</a>
    <li><a href="#File-Close">H5Fclose</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>
</ul>
</td></tr>
</table>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a>
<dt><strong>Signature:</strong>
    <dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>,
            <em>unsigned</em> <code>flags</code>,
            <em>hid_t</em> <code>access_id</code>
        )
<dt><strong>Purpose:</strong>
        <dd>Opens an existing file.
<dt><strong>Description:</strong>
        <dd><code>H5Fopen</code> opens an existing file and is the primary 
            function for accessing existing HDF5 files.  
            <p>
            The parameter <code>access_id</code> is a file access property
	      list identifier or <code>H5P_DEFAULT</code> for the default I/O access
            parameters.  
            <p>
            The <code>flags</code> argument determines whether writing 
 		to an existing file will be allowed or not.  
            The file is opened with read and write permission if 
	      <code>flags</code> is set to <code>H5F_ACC_RDWR</code>.  
            All flags may be combined with the bit-wise OR operator (`|') 
 		to change the behavior of the file open call.  
 		The more complex behaviors of a file's access are controlled 
 		through the file-access property list.
            <p>
            Files which are opened more than once return a unique identifier 
            for each <code>H5Fopen()</code> call and can be accessed 
            through all file identifiers.  
            <p>
            The return value is a file identifier for the open file and it
            should be closed by calling <code>H5Fclose()</code> when it is
            no longer needed. 
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>const char *</em><code>name</code>
            <dd>Name of the file to access.
        <dt><em>unsigned</em> <code>flags</code>
            <dd>File access flags.  See the <code>H5Fcreate</code>
                parameters list for a list of possible values.
        <dt><em>hid_t</em> <code>access_id</code>
            <dd>Identifier for the file access properties list.
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns a file identifier if successful;
        otherwise FAIL (-1).
</dl>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-Create">H5Fcreate</a>
<dt><strong>Signature:</strong>
    <dd><em>hid_t </em><code>H5Fcreate</code>(<em>const char *</em><code>name</code>,
            <em>unsigned</em> <code>flags</code>,
            <em>hid_t</em> <code>create_id</code>,
            <em>hid_t</em> <code>access_id</code>
        )
<dt><strong>Purpose:</strong>
        <dd>Creates HDF5 files.
<dt><strong>Description:</strong>
        <dd><code>H5Fcreate</code> is the primary function for creating 
            HDF5 files . 
            <p>
            The <code>flags</code> parameter determines whether an 
            existing file will be overwritten.  All newly created files 
            are opened for both reading and writing.  All flags may be 
            combined with the bit-wise OR operator (`|') to change 
            the behavior of the <code>H5Fcreate</code> call.
            <p>
            The more complex behaviors of file creation and access
            are controlled through the file-creation and file-access
            property lists.  The value of <code>H5P_DEFAULT</code> for 
            a property list value indicates that the library should use
            the default values for the appropriate property list.  Also see
            <code>H5Fpublic.h</code> for the list of supported flags. 
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>const char *</em><code>name</code>
            <dd>Name of the file to access.
        <dt><em>uintn</em> <code>flags</code>
            <dd>File access flags.  Possible values include:
                <ul><dl>
                    <dt>H5F_ACC_RDWR
                        <dd>Allow read and write access to file.
                    <dt>H5F_ACC_RDONLY
                        <dd>Allow read-only access to file.
                    <dt>H5F_ACC_TRUNC
                        <dd>Truncate file, if it already exists,  
                            erasing all data previously stored in the file.
                    <dt>H5F_ACC_EXCL
                        <dd>Fail if file already exists.
                    <dt>H5F_ACC_DEBUG
                        <dd>Print debug information.
                    <dt>H5P_DEFAULT
                        <dd>Apply default file access and creation properties.
                </dl></ul>
        <dt><em>hid_t</em> <code>create_id</code>
            <dd>File creation property list identifier, used when modifying
                default file meta-data.
        <dt><em>hid_t</em> <code>access_id</code>
            <dd>File access property list identifier.
                If parallel file access is desired, this is a collective
                call according to the communicator stored in the
                <code>access_id</code>. 
                Use <code>0</code> for default access properties.
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns a file identifier if successful;
        otherwise FAIL (-1).
</dl>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-Flush">H5Fflush</a>
<dt><strong>Signature:</strong>
    <dd><em>herr_t </em><code>H5Fis_hdf5</code>(<em>hid_t </em><code>object_id</code>
        )
<dt><strong>Purpose:</strong>
        <dd>Flushes all buffers associated with a file to disk.
<dt><strong>Description:</strong>
        <dd><code>H5Fflush</code> causes all buffers associated with a
        file to be immediately flushed to disk without removing the
        data from the cache.  
        <p>
        <code>object_id</code> can be any object associated with the file, 
        including the file itself, a dataset, a group, an attribute, or 
        a named data type.
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>const char *</em><code>object_id</code>
            <dd>Identifier of object used to identify the file.
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns SUCCEED (0) if successful;
        otherwise returns FAIL (-1).
</dl>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a>
<dt><strong>Signature:</strong>
    <dd><em>hbool_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code>
        )
<dt><strong>Purpose:</strong>
        <dd>Determines whether a file is in the HDF5 format.
<dt><strong>Description:</strong>
        <dd><code>H5Fis_hdf5</code> determines whether a file is in 
            the HDF5 format.
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>const char *</em><code>name</code>
            <dd>File name to check format.
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns <code>TRUE</code> or <code>FALSE</code> if successful.
        Otherwise returns FAIL (-1).
</dl>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetCreatePlist">H5Fget_create_plist</a>
<dt><strong>Signature:</strong>
    <dd><em>hid_t </em><code>H5Fget_create_plist</code>(<em>hid_t</em> <code>file_id</code>
        )
<dt><strong>Purpose:</strong>
        <dd>Returns a file creation property list identifier.
<dt><strong>Description:</strong>
        <dd><code>H5Fget_create_plist</code> returns a file creation 
            property list identifier identifying the creation properties 
            used to create this file.  This function is useful for 
            duplicating properties when creating another file.
            <p>
            See "File Creation Properties" in 
            <a href="RM_H5P.html">H5P: Property List Interface</a> 
            in this reference manual and 
            "File Creation Properties" 
            in <a href="Files.html"><cite>Files</cite></a> in the 
            <cite>HDF5 User's Guide</cite> for 
            additional information and related functions.
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>hid_t</em> <code>file_id</code>
            <dd>Identifier of the file to get creation property list of
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns a file creation property list identifier if successful;
        otherwise FAIL (-1).
</dl>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetAccessPlist">H5Fget_access_plist</a>
<dt><strong>Signature:</strong>
    <dd><em>hid_t </em><code>H5Fget_access_plist</code>(<em>hid_t</em> <code>file_id</code>)
<dt><strong>Purpose:</strong>
        <dd>Returns a file access property list identifier.
<dt><strong>Description:</strong>
        <dd><code>H5Fget_access_plist</code> returns the 
            file access property list identifier of the specified file.
            <p>
            See "File Access Properties" in 
            <a href="RM_H5P.html">H5P: Property List Interface</a> 
            in this reference manual and 
            "File Access Property Lists" 
            in <a href="Files.html"><cite>Files</cite></a> in the 
            <cite>HDF5 User's Guide</cite> for 
            additional information and related functions.
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>hid_t</em> <code>file_id</code>
            <dd>Identifier of file to get access property list of
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns a file access property list identifier if successful;
        otherwise FAIL (-1).
</dl>


<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a>
<dt><strong>Signature:</strong>
    <dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code>
        )
<dt><strong>Purpose:</strong>
        <dd>Terminates access to an HDF5 file.  
<dt><strong>Description:</strong>
        <dd><code>H5Fclose</code> terminates access to an HDF5 file.  
            If this is the last file identifier open for a file 
            and if access identifiers are still in use, 
            this function will fail.
<dt><strong>Parameters:</strong>
    <dl>
        <dt><em>hid_t</em> <code>file_id</code>
            <dd>Identifier of a file to terminate access to.
    </dl>
<dt><strong>Returns:</strong>
    <dd>Returns SUCCEED (0) if successful;
        otherwise FAIL (-1).
</dl>


<hr>
<center>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
<a href="RM_H5E.html">H5E</a>&nbsp;&nbsp;
H5F&nbsp;&nbsp;
<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
<a href="Tools.html">Tools</a>&nbsp;&nbsp;
<!--
<a href="Glossary.html">Glossary</a>
-->
</center>
<hr>

<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> 

<br>
Last modified:  14 August 1998

</body>
</html>