diff options
| -rw-r--r-- | doc/html/RM_H5P.html | 137 |
1 files changed, 88 insertions, 49 deletions
diff --git a/doc/html/RM_H5P.html b/doc/html/RM_H5P.html index 2c596a2..dff3ec5 100644 --- a/doc/html/RM_H5P.html +++ b/doc/html/RM_H5P.html @@ -10,9 +10,9 @@ HDF5/H5P API Specification <center> <table border=0 width=98%> <tr><td valign=top align=left> +<a href="index.html">HDF5 documents and links</a> <br> <a href="H5.intro.html">Introduction to HDF5</a> <br> -<a href="H5.user.html">HDF5 User Guide</a> <br> -<a href="index.html">Other HDF5 documents and links</a> <br> +<a href="H5.user.html">HDF5 User's Guide</a> <br> <!-- <a href="Glossary.html">Glossary</a><br> --> @@ -95,8 +95,10 @@ many different parameters to be easily manipulated. <li><a href="#Property-GetCore">H5Pget_core</a> <li><a href="#Property-SetMPI">H5Pset_mpi</a> || <li><a href="#Property-GetMPI">H5Pget_mpi</a> || +<!-- Not implemented. Probably never will be. <li><a href="#Property-SetFamily">H5Pset_family</a> <li><a href="#Property-GetFamily">H5Pget_family</a> +--> <li><a href="#Property-SetCache">H5Pset_cache</a> <li><a href="#Property-GetCache">H5Pget_cache</a> <li><a href="#Property-SetSplit">H5Pset_split</a> @@ -109,6 +111,8 @@ many different parameters to be easily manipulated. <br> <br> <br> +<br> +<br> <br> || <i>Available only in the parallel HDF5 library.</i> @@ -453,7 +457,7 @@ parallel HDF5 library.</i> <dt><strong>Parameters:</strong> <dl> <dt><em>hid_t</em> <code>plist</code> - <dd>IN: Identifier of property list to modify + <dd>IN: Identifier of property list to modify. <dt><em>MPI_Comm</em> <code>comm</code> <dd>IN: MPI communicator to be used for file open as defined in MPI_FILE_OPEN of MPI-2. This function does not make a @@ -840,7 +844,7 @@ parallel HDF5 library.</i> <dt><em>hid_t</em> <code>plist</code> <dd>IN: Identifier of property list to query. <dt><em>int</em> <code>max_ndims</code> - <dd>OUT: Size of the <code>dims</code> array. + <dd>IN: Size of the <code>dims</code> array. <dt><em>hsize_t *</em> <code>dims</code> <dd>OUT: Array to store the chunk dimensions. </dl> @@ -863,14 +867,16 @@ parallel HDF5 library.</i> <dt><strong>Description:</strong> <dd><code>H5Pset_alignment</code> sets the alignment properties of a file access property list - so that any file object >= THRESHOLD bytes will be aligned on - an address which is a multiple of ALIGNMENT. The addresses + so that any file object greater or equal in size to + <code>threshold</code> bytes will be aligned on an address + which is a multiple of <code>alignment</code>. The addresses are relative to the end of the user block; the alignment is calculated by subtracting the user block size from the absolute file address and then adjusting the address to be a - multiple of ALIGNMENT. + multiple of <code>alignment</code>. <p> - Default values for THRESHOLD and ALIGNMENT are one, implying + Default values for <code>threshold</code> and + <code>alignment</code> are one, implying no alignment. Generally the default values will result in the best performance for single-process access to the file. For MPI-IO and other parallel systems, choose an alignment @@ -881,8 +887,13 @@ parallel HDF5 library.</i> <dd>IN: Identifier for a file access property list. <dt><em>hsize_t</em> <code>threshold</code> <dd>IN: Threshold value. + Must be non-negative. + Note that setting the threshold value to 0 (zero) has + the effect of a special case, forcing everything + to be aligned. <dt><em>hsize_t</em> <code>alignment</code> <dd>IN: Alignment value. + Must be a positive value. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -970,7 +981,7 @@ parallel HDF5 library.</i> <dl> <dt><strong>Name:</strong> <a name="Property-GetExternalCount">H5Pget_external_count</a> <dt><strong>Signature:</strong> - <dd><em>int</em> <code>H5Pget_external_count</code>(<em>hid_t</em> <code>plist</code>, + <dd><em>int</em> <code>H5Pget_external_count</code>(<em>hid_t</em> <code>plist</code> ) <dt><strong>Purpose:</strong> <dd>Returns the number of external files for a dataset. @@ -1181,7 +1192,7 @@ parallel HDF5 library.</i> <dd>IN: Bit vector specifying certain general properties of the filter. <dt><em>size_t</em> <code>cd_nelmts</code> - <dd>IN: Number of elements in <code>cd_values</code> + <dd>IN: Number of elements in <code>cd_values</code>. <dt><em>const unsigned int</em> <code>cd_values[]</code> <dd>IN: Auxiliary data for the filter. </dl> @@ -1287,7 +1298,7 @@ parallel HDF5 library.</i> <dd>OUT: Bit vector specifying certain general properties of the filter. <dt><em>size_t *</em><code>cd_nelmts</code> - <dd>IN/OUT: Number of elements in <code>cd_values</code> + <dd>IN/OUT: Number of elements in <code>cd_values</code>. <dt><em>unsigned int *</em><code>cd_values</code> <dd>OUT: Auxiliary data for the filter. <dt><em>size_t</em> <code>namelen</code> @@ -1305,7 +1316,7 @@ parallel HDF5 library.</i> <dl> <dt><strong>Name:</strong> <a name="Property-GetDriver">H5Pget_driver</a> <dt><strong>Signature:</strong> - <dd><em>H5F_driver_t</em> <code>H5Pget_driver</code>(<em>hid_t</em> <code>plist</code>, + <dd><em>H5F_driver_t</em> <code>H5Pget_driver</code>(<em>hid_t</em> <code>plist</code> ) <dt><strong>Purpose:</strong> <dd>Returns a low-level file driver identifier. @@ -1383,7 +1394,7 @@ parallel HDF5 library.</i> <dl> <dt><strong>Name:</strong> <a name="Property-SetSec2">H5Pset_sec2</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_sec2</code>(<em>hid_t</em> <code>plist</code>, + <dd><em>herr_t</em> <code>H5Pset_sec2</code>(<em>hid_t</em> <code>plist</code> ) <dt><strong>Purpose:</strong> <dd>Sets the low-level file driver to use the declared functions. @@ -1443,7 +1454,7 @@ parallel HDF5 library.</i> This driver is restricted to temporary files which are not larger than the amount of virtual memory available. The <code>increment</code> argument determines the file block size - and memory will be allocated in multiples of INCREMENT bytes. + and memory will be allocated in multiples of <code>increment</code> bytes. A liberal <code>increment</code> results in fewer calls to <code>realloc()</code> and probably less memory fragmentation. <dt><strong>Parameters:</strong> @@ -1452,6 +1463,7 @@ parallel HDF5 library.</i> <dd>IN: Identifier of a file access property list. <dt><em>size_t</em> <code>increment</code> <dd>IN: File block size in bytes. + Must be a positive value. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -1508,11 +1520,11 @@ parallel HDF5 library.</i> raw data in another file. The meta file will have a name which is formed by adding <em>meta_extension</em> (recommended default value: <code>.meta</code>) to the end of the base name - and will be accessed according to the <em>meta_properties</em>. + and will be accessed according to the <em>meta_plist</em>. The raw file will have a name which is formed by appending <em>raw_extension</em> (recommended default value: <code>.raw</code>) to the base name and will be accessed according - to the <em>raw_properties</em>. + to the <em>raw_plist</em>. Additional parameters may be added to this function in the future. <dt><strong>Parameters:</strong> <dl> @@ -1542,10 +1554,10 @@ parallel HDF5 library.</i> <dd><em>herr_t</em> <code>H5Pget_split</code>(<em>hid_t</em> <code>plist</code>, <em>size_t</em> <code>meta_ext_size</code>, <em>char</em> <code>*meta_ext</code>, - <em>hid_t</em> <code>*meta_properties</code>, + <em>hid_t</em> <code>*meta_plist</code>, <em>size_t</em> <code>raw_ext_size</code>, <em>char</em> <code>*raw_ext</code>, - <em>hid_t</em> <code>*raw_properties</code> + <em>hid_t</em> <code>*raw_plist</code> ) <dt><strong>Purpose:</strong> <dd>Determines whether the file access property list is set @@ -1554,7 +1566,7 @@ parallel HDF5 library.</i> <dd><code>H5Pget_split</code> checks to determine whether the file access property list is set to the split driver. On successful return, - <code>meta_properties</code> and <code>raw_properties</code> will + <code>meta_plist</code> and <code>raw_plist</code> will point to copies of the meta and raw access property lists which should be closed by calling <code>H5Pclose()</code> when the application is finished with them, but if the meta and/or @@ -1578,14 +1590,14 @@ parallel HDF5 library.</i> copied to the <code>meta_ext</code> buffer. <dt><em>char</em> <code>*meta_ext</code> <dd>OUT: Meta file extension. - <dt><em>hid_t</em> <code>*meta_properties</code> + <dt><em>hid_t</em> <code>*meta_plist</code> <dd>OUT: Pointer to a copy of the meta file access property list. <dt><em>size_t</em> <code>raw_ext_size</code> <dd>IN: Number of characters of the raw file extension to be copied to the <code>raw_ext</code> buffer. <dt><em>char</em> <code>*raw_ext</code> <dd>OUT: Raw file extension. - <dt><em>hid_t</em> <code>*raw_properties</code> + <dt><em>hid_t</em> <code>*raw_plist</code> <dd>OUT: Pointer to a copy of the raw file access property list. </dl> <dt><strong>Returns:</strong> @@ -1599,7 +1611,7 @@ parallel HDF5 library.</i> <dl> <dt><strong>Name:</strong> <a name="Property-SetGCReferences">H5Pset_gc_references</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pset_split</code>(<em>hid_t</em> <code>plist</code>, + <dd><em>herr_t</em> <code>H5Pset_gc_references</code>(<em>hid_t</em> <code>plist</code>, <em>unsigned</em> <code>gc_ref</code> ) <dt><strong>Purpose:</strong> @@ -1624,7 +1636,8 @@ parallel HDF5 library.</i> <dt><em>hid_t</em> <code>plist</code> <dd>IN: File access property list identifier. <dt><em>unsigned</em> <code>gc_ref</code> - <dd>IN: + <dd>IN: Flag setting reference garbage collection to + on (<code>1</code>) or off (<code>0</code>). </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -1635,7 +1648,7 @@ parallel HDF5 library.</i> <dl> <dt><strong>Name:</strong> <a name="Property-GetGCReferences">H5Pget_gc_references</a> <dt><strong>Signature:</strong> - <dd><em>herr_t</em> <code>H5Pget_split</code>(<em>hid_t</em> <code>plist</code>, + <dd><em>herr_t</em> <code>H5Pget_gc_references</code>(<em>hid_t</em> <code>plist</code>, <em>unsigned</em> *<code>gc_ref</code> ) <dt><strong>Purpose:</strong> @@ -1651,7 +1664,10 @@ parallel HDF5 library.</i> <dt><em>hid_t</em> <code>plist</code> <dd>IN: File access property list identifier. <dt><em>unsigned</em> <code>gc_ref</code> - <dd>OUT: + <dd>OUT: Flag returning the state of reference garbage collection. + A returned value of <code>1</code> indicates that + garbage collection is on while + <code>0</code> indicates that garbage collection is off. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -1659,6 +1675,7 @@ parallel HDF5 library.</i> </dl> +<!-- Not implemented. Probably never will be. <hr> <dl> <dt><strong>Name:</strong> <a name="Property-SetFamily">H5Pset_family</a> @@ -1668,11 +1685,10 @@ parallel HDF5 library.</i> <em>hid_t</em> <code>memb_plist</code> ) <dt><strong>Purpose:</strong> - <dd>Sets the file access properties list to the <code>family</code> - driver. + <dd>Sets the file access properties list to the family driver. <dt><strong>Description:</strong> <dd><code>H5Pset_family</code> sets the file access properties - to use the <code>family</code> driver; any previously defined + to use the family driver; any previously defined driver properties are erased from the property list. See <a href="Files.html#File_Families">File Families</a> in the <cite>HDF5 User's Guide</cite> for a discussion @@ -1749,6 +1765,7 @@ parallel HDF5 library.</i> to the family driver. Otherwise returns a negative value. </dl> +--> <hr> @@ -1819,8 +1836,8 @@ parallel HDF5 library.</i> <dt><strong>Description:</strong> <dd>Retrieves the maximum possible number of elements in the meta data cache and raw data chunk cache, the maximum possible number of - bytes in the raw data chunk cache, and the preemption policy value, - <em>rdcc_w0</em>. + bytes in the raw data chunk cache, and the preemption policy value. + <p> Any (or all) arguments may be null pointers in which case the corresponding datum is not returned. <dt><strong>Parameters:</strong> @@ -1857,11 +1874,21 @@ parallel HDF5 library.</i> indicates whether to cache hyperslab blocks during I/O, a process which can significantly increase I/O speeds. <p> + When working with hyperslab selections, it is possible to + significantly speed up I/O operations by retrieving an + entire hyperslab from the file in one operation and + caching it in memory. + The <code>cache</code> parameter specifies whether to turn + caching on for hyperslab I/O operations. + If <code>cache</code> is set to <code>1</code>, + caching is turned on; + if set to <code>0</code>, caching is turned off. + <p> The parameter <code>limit</code> sets the maximum size of the hyperslab block to cache. If a block is smaller than that limit, it may still not be cached if no memory is available. - Setting the limit to <code>0</code> (zero) indicates no limitation on the size of - block to attempt to cache. + Setting <code>limit</code> to <code>0</code> (zero) indicates + no limitation on the size of block to attempt to cache. <p> The default is to cache blocks with no limit on block size for serial I/O and to not cache blocks for parallel I/O. @@ -1870,7 +1897,8 @@ parallel HDF5 library.</i> <dt><em>hid_t</em> <code>plist</code> <dd>IN: Dataset transfer property list identifier. <dt><em>unsigned</em> <code>cache</code> - <dd>IN: + <dd>IN: A flag indicating whether caching is to be + set to on (<code>1</code>) or off (<code>0</code>). <dt><em>unsigned</em> <code>limit</code> <dd>IN: Maximum size of the hyperslab block to cache. <code>0</code> (zero) indicates no limit. @@ -1886,8 +1914,8 @@ parallel HDF5 library.</i> <dt><strong>Name:</strong> <a name="Property-GetHyperCache">H5Pget_hyper_cache</a> <dt><strong>Signature:</strong> <dd><em>herr_t</em> <code>H5Pget_hyper_cache</code>(<em>hid_t</em> <code>plist</code>, - <em>unsigned</em> <code>cache</code>, - <em>unsigned</em> <code>limit</code> + <em>unsigned</em> *<code>cache</code>, + <em>unsigned</em> *<code>limit</code> ) <dt><strong>Purpose:</strong> <dd>Returns information regarding the caching of hyperslab blocks during I/O. @@ -1899,9 +1927,10 @@ parallel HDF5 library.</i> <dl> <dt><em>hid_t</em> <code>plist</code> <dd>IN: Dataset transfer property list identifier. - <dt><em>unsigned</em> <code>cache</code> - <dd>OUT: - <dt><em>unsigned</em> <code>limit</code> + <dt><em>unsigned</em> *<code>cache</code> + <dd>OUT: A flag indicating whether caching is + set to on (<code>1</code>) or off (<code>0</code>). + <dt><em>unsigned</em> *<code>limit</code> <dd>OUT: Maximum size of the hyperslab block to cache. <code>0</code> (zero) indicates no limit. </dl> @@ -2029,7 +2058,7 @@ parallel HDF5 library.</i> <dt><em>hid_t</em> <code>plist</code> <dd>IN: Identifier for the dataset transfer property list. <dt><em>size_t</em> <code>size</code> - <dd>IN: Size for the type conversion and background buffers. + <dd>IN: Size, in bytes, of the type conversion and background buffers. <dt><em>void</em> <code>tconv</code> <dd>IN: Pointer to application-allocated type conversion buffer. <dt><em>void</em> <code>bkg</code> @@ -2066,7 +2095,7 @@ parallel HDF5 library.</i> background buffer. </dl> <dt><strong>Returns:</strong> - <dd>Returns buffer size if successful; + <dd>Returns buffer size, in bytes, if successful; otherwise 0 on failure. </dl> @@ -2332,15 +2361,21 @@ parallel HDF5 library.</i> <dt><em>hid_t</em> <code>plist</code> <dd>IN: Identifier for the dataset transfer property list. <dt><em>H5MM_allocate_t</em> <code>alloc</code> - <dd>IN: User's allocate routine, or <code> NULL</code> for system <code> malloc</code>. + <dd>IN: User's allocate routine, or + <code> NULL</code> for system <code> malloc</code>. <dt><em>void</em> *<code>alloc_info</code> <dd>IN: Extra parameter for user's allocation routine. - Ignored if preceding parameter is <code> NULL</code>. + <br> + Contents are ignored if preceding parameter is + <code>NULL</code>. <dt><em>H5MM_free_t</em> <code>free</code> - <dd>IN: User's free routine, or <code> NULL</code> for system <code>free</code>. + <dd>IN: User's free routine, or <code> NULL</code> + for system <code>free</code>. <dt><em>void</em> *<code>free_info</code> <dd>IN: Extra parameter for user's free routine. - Ignored if preceding parameter is <code> NULL</code>. + <br> + Contents are ignored if preceding parameter is + <code>NULL</code>. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -2360,7 +2395,7 @@ parallel HDF5 library.</i> ) <dt><strong>Purpose:</strong> <dd>Gets the memory manager for variable-length datatype allocation in - <code>H5Dread</code> and <code>H5Treclaim_vlen</code>. + <code>H5Dread</code> and <code>H5Dvlen_reclaim</code>. <dt><strong>Description:</strong> <dd><code>H5Pget_vlen_mem_manager</code> is the companion function to <code>H5Pset_vlen_mem_manager</code>, returning the parameters @@ -2374,13 +2409,17 @@ parallel HDF5 library.</i> for system <code> malloc</code>. <dt><em>void</em> *<code>alloc_info</code> <dd>OUT: Extra parameter for user's allocation routine. - Ignored if preceding parameter is <code> NULL</code>. + <br> + Contents are ignored if preceding parameter is + <code> NULL</code>. <dt><em>H5MM_free_t</em> <code>free</code> <dd>OUT: User's free routine, or <code> NULL</code> for system <code>free</code>. <dt><em>void</em> *<code>free_info</code> <dd>OUT: Extra parameter for user's free routine. - Ignored if preceding parameter is <code> NULL</code>. + <br> + Contents are ignored if preceding parameter is + <code> NULL</code>. </dl> <dt><strong>Returns:</strong> <dd>Returns a non-negative value if successful; @@ -2392,9 +2431,9 @@ parallel HDF5 library.</i> <center> <table border=0 width=98%> <tr><td valign=top align=left> +<a href="index.html">HDF5 documents and links</a> <br> <a href="H5.intro.html">Introduction to HDF5</a> <br> -<a href="H5.user.html">HDF5 User Guide</a> <br> -<a href="index.html">Other HDF5 documents and links</a> <br> +<a href="H5.user.html">HDF5 User's Guide</a> <br> <!-- <a href="Glossary.html">Glossary</a><br> --> |