<html> <head><title> HDF5/H5F Draft API Specification </title></head> <body> <hr> <center> <a href="RM_H5Front.html">HDF5 Reference Manual</a> <a href="RM_H5.html">H5</a> <a href="RM_H5A.html">H5A</a> <a href="RM_H5D.html">H5D</a> <a href="RM_H5E.html">H5E</a> H5F <a href="RM_H5G.html">H5G</a> <a href="RM_H5P.html">H5P</a> <a href="RM_H5S.html">H5S</a> <a href="RM_H5T.html">H5T</a> <a href="RM_H5Z.html">H5Z</a> <a href="Tools.html">Tools</a> <!-- <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> </td><td valign=top> <ul> <li><a href="#File-Flush">H5Fflush</a> <li><a href="#File-Close">H5Fclose</a> </ul> </td><td> </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> <a href="RM_H5.html">H5</a> <a href="RM_H5A.html">H5A</a> <a href="RM_H5D.html">H5D</a> <a href="RM_H5E.html">H5E</a> H5F <a href="RM_H5G.html">H5G</a> <a href="RM_H5P.html">H5P</a> <a href="RM_H5S.html">H5S</a> <a href="RM_H5T.html">H5T</a> <a href="RM_H5Z.html">H5Z</a> <a href="Tools.html">Tools</a> <!-- <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>