summaryrefslogtreecommitdiffstats
path: root/doc/html/RM_H5.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/RM_H5.html')
-rw-r--r--doc/html/RM_H5.html73
1 files changed, 62 insertions, 11 deletions
diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html
index f651183..03b75c2 100644
--- a/doc/html/RM_H5.html
+++ b/doc/html/RM_H5.html
@@ -290,21 +290,72 @@ facilitate moving easily between them.</i>
<em>unsigned</em> <code>relnum</code>
)
<dt><strong>Purpose:</strong>
- <dd>
+ <dd>Verifies that library versions are consistent.
<dt><strong>Description:</strong>
- <dd><code>H5check_version</code> verifies that the arguments match the
- version numbers compiled into the library. This function is intended
- to be called by the user to verify that the version of the header files
- compiled into the application matches the version of the HDF5 library
- being used.
+ <dd><code>H5check_version</code> verifies that the arguments provided
+ with the function call match the version numbers compiled into
+ the library.
+ <p>
+ <code>H5check_version</code> serves two slightly differing purposes.
+ <p>
+ First, the function is intended to be called by the user to verify
+ that the version of the header files compiled into an application
+ matches the version of the HDF5 library being used.
+ One may look at the <code>H5check</code> definition in the file
+ <code>H5public.h</code> as an example.
<p>
Due to the risks of data corruption or segmentation faults,
<code>H5check_version</code> causes the application to abort if the
version numbers do not match.
- <p>
- If the version numbers of the library do not match
- the version numbers in the header files being checked, the library calls the
+ The abort is achieved by means of a call to the
standard C function <code>abort()</code>.
+ <p>
+ Note that <code>H5check_version</code> verifies only the
+ major and minor version numbers and the release number;
+ it does not verify the sub-release value as that should be
+ an empty string for any official release.
+ This means that any two incompatible library versions must
+ have different {major,minor,release} numbers. (Notice the
+ reverse is not necessarily true.)
+ <p>
+ Secondarily, <code>H5check_version</code> verifies that the
+ library version identifiers <code>H5_VERS_MAJOR</code>,
+ <code>H5_VERS_MINOR</code>, <code>H5_VERS_RELEASE</code>,
+ <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code>
+ are consistent.
+ This is designed to catch source code inconsistencies,
+ but does not generate the fatal error as in the first stage
+ because this inconsistency does not cause errors in the data files.
+ If this check reveals inconsistencies, the library issues a warning
+ but the function does not fail.
+<!--
+ <p>
+<strong><em>Alternate to preceding paragraph / More to the point?</em></strong>
+<br>
+ If the function passes the above test and does not generate
+ an <code>abort()</code> call, the function's second purpose
+ comes into play.
+ <code>H5check_version</code> then procedes to verify
+ that the additional library version identifiers
+ <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code>
+ are consistent.
+ This is designed to catch source code inconsistencies,
+ but does not generate the fatal error
+ that is generated under the first function.
+ <p>
+ The version and release numbers passed as
+ <code>H5check_version</code> parameters have the
+ following relationsips to each other:
+ <dir>
+ An official HDF5 release is labelled as
+ <br>
+ HDF5 Release &lt;<code>majnum</code>&gt;<strong>.</strong>&lt;<code>minnum</code>&gt;<strong>.</strong>&lt;<code>relnum</code>&gt;
+ </dir>
+ For example, in the version of the library known as HDF5 Release 1.4.2,
+ the 1 is the major version number, <code>majnum</code>;
+ the 1 is the minor version number, <code>minnum</code>; and
+ the 1 is the release number, <code>relnum</code>.
+-->
<dt><strong>Parameters:</strong>
<dl>
<dt><em>unsigned </em><code>majnum</code>
@@ -369,10 +420,10 @@ H5&nbsp;&nbsp;
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
<br>
-Last modified: 20 March 2001
+Last modified: 2 August 2001
<br>
-Describes HDF5 Release 1.5, Unreleased Development Branch
+Describes HDF5 Release 1.5, Unreleased Development Branch
</body>