diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:37:39 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:37:39 (GMT) |
| commit | 3e213ecf064638989c816ba3a10b3b6c6307fdad (patch) | |
| tree | 46469ba129015faaf4d275b20f8f2b033c1461d6 /doc/src/RM_H5F.html | |
| parent | 3a4ad842e1fde72698b45f5d143b46076a643756 (diff) | |
| download | hdf5-3e213ecf064638989c816ba3a10b3b6c6307fdad.zip hdf5-3e213ecf064638989c816ba3a10b3b6c6307fdad.tar.gz hdf5-3e213ecf064638989c816ba3a10b3b6c6307fdad.tar.bz2 | |
[svn-r502] HDF5 Reference Manual
Final updates for Alpha2.
All currently-implemented functions added.
Technical content verified.
Diffstat (limited to 'doc/src/RM_H5F.html')
| -rw-r--r-- | doc/src/RM_H5F.html | 241 |
1 files changed, 174 insertions, 67 deletions
diff --git a/doc/src/RM_H5F.html b/doc/src/RM_H5F.html index f8e25f4..926d7ba 100644 --- a/doc/src/RM_H5F.html +++ b/doc/src/RM_H5F.html @@ -5,6 +5,23 @@ HDF5/H5F Draft API Specification <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="Glossary.html">Glossary</a> +</center> +<hr> + <center> <h1>H5F: File Interface</h1> </center> @@ -34,160 +51,250 @@ documented below. </td></tr> </table> -<hr> +<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>uintn</em> <code>flags</code>, - <em>hid_t</em> <code>access_template</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>This is the primary function for opening existing HDF5 files. - The <code>flags</code> parameter determines the file access mode. - There is no read flag, all open files are implicitily opened for - read access. - All flags may be combined with the '|' (boolean OR operator) to - change the behavior of the file open call. - The <code>access_template</code> parameter is a template containing - additional information required for specific methods of access, - parallel I/O for example. The paramters for access templates are - described in the H5P API documentation. + <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>uintn</em> <code>flags</code> - <dd>File access flags: - <ul><dl> - <dt>H5F_ACC_RDWR - <dd>Allow read and write access to file. - </dl></ul> - <dt><em>hid_t</em><code>access_template</code> - <dd>Template indicating the file access properties. - If parallel file access is desired, this is a collective - call according to the communicator stored in the - access_template. Use 0 for default access template. + <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>A file identifier if successful; + <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>uintn</em> <code>flags</code>, - <em>hid_t</em> <code>create_template</code>, - <em>hid_t</em> <code>access_template</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>This is the primary function for opening and creating HDF5 files. - The <code>flags</code> parameter determines whether an existing - file will be overwritten or not. All newly created files are opened - for both reading and writing. - All flags may be combined with the '|' (boolean OR operator) to - change the behavior of the file open call. - The <code>create_template</code> and <code>access_template</code> - parameters are templates containing additional information required - for specific methods of access or particular aspects of the file - to set when creating a file. - The parameters for creation and access templates are - described in the H5P API documentation. + <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 template value indicates that the library should use + the default values for the appropriate template. 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: + <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. The file will - be truncated, erasing all data previously stored in - the file. + <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_template</code> - <dd>File creation template ID, used when modifying default file meta-data - <dt><em>hid_t</em><code>access_template</code> - <dd>Template indicating the file access properties. + <dt><em>hid_t</em> <code>create_id</code> + <dd>File creation template 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 - access_template. Use 0 for default access template. + <code>access_template</code>. + Use <code>0</code> for default access template. </dl> <dt><strong>Returns:</strong> - <dd>An ID (of type <em>hid_t</em>) for the file upon success, - otherwise negative + <dd>Returns a file identifier if successful; + otherwise 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>This function determines whether a file is in the HDF5 format. + <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>TRUE/FALSE/negative + <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-GetCreateTemplate">H5Fget_create_template</a> <dt><strong>Signature:</strong> <dd><em>hid_t </em><code>H5Fget_create_template</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>This function returns an template ID with a copy of the parameters - used to create this file. Useful for duplicating the parameters - when creating another file. + <dd><code>H5Fget_create_template</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>File ID to get creation template of + <dd>Identifier of the file to get creation property list of </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns a file creation property list identifier if successful; + otherwise FAIL (-1). </dl> + +<hr> +<dl> +<dt><strong>Name:</strong> <a name="File-GetAccessTemplate">H5Fget_access_template</a> +<dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Fget_access_template</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_template</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>This function terminates access to an HDF5 file. If this is the - last file ID open for a file and if access IDs are still in use, + <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>File ID to terminate access to. + <dd>Identifier of a file to terminate access to. </dl> <dt><strong>Returns:</strong> - <dd>zero/negative + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). </dl> -<hr> <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="Glossary.html">Glossary</a> +</center> +<hr> <address> -<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> -<br> -<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> +<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> -Last modified: 29 June 1998 +Last modified: 14 July 1998 </body> </html> |