diff options
author | Frank Baker <fbaker@hdfgroup.org> | 2003-10-07 19:18:32 (GMT) |
---|---|---|
committer | Frank Baker <fbaker@hdfgroup.org> | 2003-10-07 19:18:32 (GMT) |
commit | 5956fb63812e9156af8549f31fef9e3e6a93c5bd (patch) | |
tree | f3631735138242ebb1a45c69c60db33d4ea4227d /doc/html/RM_H5.html | |
parent | 03dd1f7e2fafcff208542cbaa56f9e6bc16056d7 (diff) | |
download | hdf5-5956fb63812e9156af8549f31fef9e3e6a93c5bd.zip hdf5-5956fb63812e9156af8549f31fef9e3e6a93c5bd.tar.gz hdf5-5956fb63812e9156af8549f31fef9e3e6a93c5bd.tar.bz2 |
[svn-r7565]
Purpose:
Aphabetic sort of RM function entries
Minor formatting
Platforms tested:
IE 5, Safari
Diffstat (limited to 'doc/html/RM_H5.html')
-rw-r--r-- | doc/html/RM_H5.html | 406 |
1 files changed, 212 insertions, 194 deletions
diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html index 95e5598..2c770e7 100644 --- a/doc/html/RM_H5.html +++ b/doc/html/RM_H5.html @@ -60,8 +60,7 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><center> +<hr><!-- #EndLibraryItem --><center> <h1>H5: General Library Functions</h1> </center> @@ -96,29 +95,36 @@ and it users. <table border="0"> <tr> + <td valign="top"> + <ul> <li><a href="#Library-VersCheck">H5check_version</a> <li><a href="#Library-Close">H5close</a> - <li><a href="#Library-DontAtExit">H5dont_atexit</a> + <li><a href="#Library-DontAtExit">H5dont_atexit</a> + </ul> </td> <td> </td> <td valign="top"> + <ul> <li><a href="#Library-GarbageCollect">H5garbage_collect</a> <li><a href="#Library-Version">H5get_libversion</a> <li><a href="#Library-Open">H5open</a> + </ul> </td> <td> </td> <td valign="top"> + <ul> <li><a href="#Library-SetFreeListLimits">H5set_free_list_limits</a> + </ul> </td> </tr> </table> -<p> +<br> <strong>The FORTRAN90 Interfaces:</strong> <br> @@ -132,6 +138,7 @@ information. You will probably want to adjust the size and location of this external window so that both browser windows are visible and to facilitate moving easily between them.</i> </font> +<br> <table border=0> <tr><td valign=top> @@ -153,28 +160,98 @@ facilitate moving easily between them.</i> </td></tr> </table> - +<!-- NEW PAGE --> +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5check_version" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-Open">H5open</a> +<dt><strong>Name:</strong> <a name="Library-VersCheck">H5check_version</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5open</code>(<em>void</em>) + <dd><em>herr_t</em> <code>H5check_version</code>(<em>unsigned</em> <code>majnum</code>, + <em>unsigned</em> <code>minnum</code>, + <em>unsigned</em> <code>relnum</code> + ) <dt><strong>Purpose:</strong> - <dd>Initializes the HDF5 library. + <dd>Verifies that library versions are consistent. <dt><strong>Description:</strong> - <dd><code>H5open</code> initialize the library. This function is - normally called automatically, but if you find that an - HDF5 library function is failing inexplicably, try calling - this function first. + <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. + 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 <<code>majnum</code>><strong>.</strong><<code>minnum</code>><strong>.</strong><<code>relnum</code>> + </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>None. + <dt><em>unsigned </em><code>majnum</code> + <dd>IN: The major version of the library. + <dt><em>unsigned </em><code>minnum</code> + <dd>IN: The minor version of the library. + <dt><em>unsigned </em><code>relnum</code> + <dd>IN: The release number of the library. </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful; - otherwise returns a negative value. + <dd>Returns a non-negative value if successful. + Upon failure, this function causes the application to abort. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5_FORTRAN.html#h5open_f" + <dd><a href="fortran/h5_FORTRAN.html#h5check_version_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -182,7 +259,8 @@ facilitate moving easily between them.</i> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5close" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Library-Close">H5close</a> @@ -213,78 +291,47 @@ facilitate moving easily between them.</i> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5H5dont_atexit" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-SetFreeListLimits">H5set_free_list_limits</a> +<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5set_free_list_limits</code>(<em>int</em> <code>reg_global_lim</code>, - <em>int</em> <code>reg_list_lim</code>, - <em>int</em> <code>arr_global_lim</code>, - <em>int</em> <code>arr_list_lim</code>, - <em>int</em> <code>blk_global_lim</code>, - <em>int</em> <code>blk_list_lim</code> - ) + <dd><em>herr_t</em> <code>H5dont_atexit</code>(<em>void</em>) <dt><strong>Purpose:</strong> - <dd>Sets free-list size limits. + <dd>Instructs library not to install <code>atexit</code> cleanup routine. <dt><strong>Description:</strong> - <dd><code>H5set_free_list_limits</code> sets size limits - on all types of free lists. - The HDF5 library uses free lists internally to manage memory. - There are three types of free lists: - <ul><li><span class=termDef>Regular</span> - free lists manage a single data structure. - <li><span class=termDef>Array</span> - free lists manage arrays of a data structure. - <li><span class=termDef>Block</span> - free lists manage blocks of bytes. - </ul> - <em>Alternate phrasing?</em>: - <ul><li><span class=termDef>Regular</span> - free lists manage data structures containing atomic data. - <li><span class=termDef>Array</span> - free lists manage data structures containing array data. - <li><span class=termDef>Block</span> - free lists manage blocks of bytes. - </ul> - <p> - These are global limits, but each limit applies only to - free lists of the specified type. - Therefore, if an application sets a 1Mb limit on each of - the global lists, up to 3Mb of total storage might be - allocated, 1Mb for each of the regular, array, and - block type lists. - <p> - Using a value of <code?>-1</code> for a limit means that - no limit is set for the specified type of free list. + <dd><code>H5dont_atexit</code> indicates to the library that an + <code>atexit()</code> cleanup routine should not be installed. + The major purpose for this is in situations where the + library is dynamically linked into an application and is + un-linked from the application before <code>exit()</code> gets + called. In those situations, a routine installed with + <code>atexit()</code> would jump to a routine which was + no longer in memory, causing errors. + <p> + In order to be effective, this routine <em>must</em> be called + before any other HDF function calls, and must be called each + time the library is loaded/linked into the application + (the first time and after it's been un-loaded). <dt><strong>Parameters:</strong> <dl> - <dt><em>int</em> <code>reg_global_lim</code> - <dd>IN: The limit on all regular free list memory used - <dt><em>int</em> <code>reg_list_lim</code> - <dd>IN: The limit on memory used in each regular free list - <dt><em>int</em> <code>arr_global_lim</code> - <dd>IN: The limit on all array free list memory used - <dt><em>int</em> <code>arr_list_lim</code> - <dd>IN: The limit on memory used in each array free list - <dt><em>int</em> <code>blk_global_lim</code> - <dd>IN: The limit on all block free list memory used - <dt><em>int</em> <code>blk_list_lim</code> - <dd>IN: The limit on memory used in each block free list + <dt>None. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5_FORTRAN.html#h5set_free_list_limits_f" + <dd><a href="fortran/h5_FORTRAN.html#h5dont_atexit_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5garbage_collect" --> <hr> <dl> <dt><strong>Name:</strong> <a name="Library-GarbageCollect">H5garbage_collect</a> @@ -322,37 +369,36 @@ facilitate moving easily between them.</i> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5get_libversion" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-DontAtExit">H5dont_atexit</a> +<dt><strong>Name:</strong> <a name="Library-Version">H5get_libversion</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5dont_atexit</code>(<em>void</em>) + <dd><em>herr_t</em> <code>H5get_libversion</code>(<em>unsigned *</em><code>majnum</code>, + <em>unsigned *</em><code>minnum</code>, + <em>unsigned *</em><code>relnum</code> + ) <dt><strong>Purpose:</strong> - <dd>Instructs library not to install <code>atexit</code> cleanup routine. + <dd>Returns the HDF library release number. <dt><strong>Description:</strong> - <dd><code>H5dont_atexit</code> indicates to the library that an - <code>atexit()</code> cleanup routine should not be installed. - The major purpose for this is in situations where the - library is dynamically linked into an application and is - un-linked from the application before <code>exit()</code> gets - called. In those situations, a routine installed with - <code>atexit()</code> would jump to a routine which was - no longer in memory, causing errors. - <p> - In order to be effective, this routine <em>must</em> be called - before any other HDF function calls, and must be called each - time the library is loaded/linked into the application - (the first time and after it's been un-loaded). + <dd><code>H5get_libversion</code> retrieves the major, minor, and release + numbers of the version of the HDF library which is linked to + the application. <dt><strong>Parameters:</strong> <dl> - <dt>None. + <dt><em>unsigned *</em><code>majnum</code> + <dd>OUT: The major version of the library. + <dt><em>unsigned *</em><code>minnum</code> + <dd>OUT: The minor version of the library. + <dt><em>unsigned *</em><code>relnum</code> + <dd>OUT: The release number of the library. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5_FORTRAN.html#h5dont_atexit_f" + <dd><a href="fortran/h5_FORTRAN.html#h5get_libversion_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> <!-- <img src="Graphics/Java.gif"> @@ -360,134 +406,105 @@ facilitate moving easily between them.</i> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5open" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-Version">H5get_libversion</a> +<dt><strong>Name:</strong> <a name="Library-Open">H5open</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5get_libversion</code>(<em>unsigned *</em><code>majnum</code>, - <em>unsigned *</em><code>minnum</code>, - <em>unsigned *</em><code>relnum</code> - ) + <dd><em>herr_t</em> <code>H5open</code>(<em>void</em>) <dt><strong>Purpose:</strong> - <dd>Returns the HDF library release number. + <dd>Initializes the HDF5 library. <dt><strong>Description:</strong> - <dd><code>H5get_libversion</code> retrieves the major, minor, and release - numbers of the version of the HDF library which is linked to - the application. + <dd><code>H5open</code> initialize the library. This function is + normally called automatically, but if you find that an + HDF5 library function is failing inexplicably, try calling + this function first. <dt><strong>Parameters:</strong> <dl> - <dt><em>unsigned *</em><code>majnum</code> - <dd>OUT: The major version of the library. - <dt><em>unsigned *</em><code>minnum</code> - <dd>OUT: The minor version of the library. - <dt><em>unsigned *</em><code>relnum</code> - <dd>OUT: The release number of the library. + <dt>None. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5_FORTRAN.html#h5get_libversion_f" - target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> + <dd> +<a href="fortran/h5_FORTRAN.html#h5open_f" target="FortranWin"> +<img src="Graphics/FORTRAN.gif" border=0></a> + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> </dl> - +<!-- NEW PAGE --> +<!-- HEADER RIGHT "H5set_free_list_limits" --> <hr> <dl> -<dt><strong>Name:</strong> <a name="Library-VersCheck">H5check_version</a> +<dt><strong>Name:</strong> <a name="Library-SetFreeListLimits">H5set_free_list_limits</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5check_version</code>(<em>unsigned</em> <code>majnum</code>, - <em>unsigned</em> <code>minnum</code>, - <em>unsigned</em> <code>relnum</code> - ) + <dd><em>herr_t</em> <code>H5set_free_list_limits</code>(<em>int</em> <code>reg_global_lim</code>, + <em>int</em> <code>reg_list_lim</code>, + <em>int</em> <code>arr_global_lim</code>, + <em>int</em> <code>arr_list_lim</code>, + <em>int</em> <code>blk_global_lim</code>, + <em>int</em> <code>blk_list_lim</code> + ) <dt><strong>Purpose:</strong> - <dd>Verifies that library versions are consistent. + <dd>Sets free-list size limits. <dt><strong>Description:</strong> - <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. - 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 <<code>majnum</code>><strong>.</strong><<code>minnum</code>><strong>.</strong><<code>relnum</code>> - </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>. ---> + <dd><code>H5set_free_list_limits</code> sets size limits + on all types of free lists. + The HDF5 library uses free lists internally to manage memory. + There are three types of free lists: + <ul><li><span class=termDef>Regular</span> + free lists manage a single data structure. + <li><span class=termDef>Array</span> + free lists manage arrays of a data structure. + <li><span class=termDef>Block</span> + free lists manage blocks of bytes. + </ul> + <em>Alternate phrasing?</em>: + <ul><li><span class=termDef>Regular</span> + free lists manage data structures containing atomic data. + <li><span class=termDef>Array</span> + free lists manage data structures containing array data. + <li><span class=termDef>Block</span> + free lists manage blocks of bytes. + </ul> + <p> + These are global limits, but each limit applies only to + free lists of the specified type. + Therefore, if an application sets a 1Mb limit on each of + the global lists, up to 3Mb of total storage might be + allocated, 1Mb for each of the regular, array, and + block type lists. + <p> + Using a value of <code>-1</code> for a limit means that + no limit is set for the specified type of free list. <dt><strong>Parameters:</strong> <dl> - <dt><em>unsigned </em><code>majnum</code> - <dd>IN: The major version of the library. - <dt><em>unsigned </em><code>minnum</code> - <dd>IN: The minor version of the library. - <dt><em>unsigned </em><code>relnum</code> - <dd>IN: The release number of the library. + <dt><em>int</em> <code>reg_global_lim</code> + <dd>IN: The limit on all regular free list memory used + <dt><em>int</em> <code>reg_list_lim</code> + <dd>IN: The limit on memory used in each regular free list + <dt><em>int</em> <code>arr_global_lim</code> + <dd>IN: The limit on all array free list memory used + <dt><em>int</em> <code>arr_list_lim</code> + <dd>IN: The limit on memory used in each array free list + <dt><em>int</em> <code>blk_global_lim</code> + <dd>IN: The limit on all block free list memory used + <dt><em>int</em> <code>blk_list_lim</code> + <dd>IN: The limit on memory used in each block free list </dl> <dt><strong>Returns:</strong> - <dd>Returns a non-negative value if successful. - Upon failure, this function causes the application to abort. + <dd>Returns a non-negative value if successful; + otherwise returns a negative value. <dt><strong>Non-C API(s):</strong> - <dd><a href="fortran/h5_FORTRAN.html#h5check_version_f" + <dd><a href="fortran/h5_FORTRAN.html#h5set_free_list_limits_f" target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a> - <!-- + <!-- <img src="Graphics/Java.gif"> <img src="Graphics/C++.gif"> --> @@ -527,14 +544,15 @@ And in this document, the </td></tr> </table> </center> -<hr> -<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> +<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> <br> Describes HDF5 Release 1.6.0, July 2003 -</address><!-- #EndLibraryItem --> - -Last modified: 6 June 2003 +</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT"> +<!-- +document.writeln("Last modified: 3 October 2003"); +--> +</SCRIPT> </body> </html> |