diff options
author | lrknox <lrknox@users.noreply.github.com> | 2023-07-21 00:49:17 (GMT) |
---|---|---|
committer | lrknox <lrknox@users.noreply.github.com> | 2023-07-21 00:49:17 (GMT) |
commit | 175161c045ec8f1cc69b22030e416b60f40d5343 (patch) | |
tree | 9141df9563c2079e5b21245b7b5ca7e77a11066a /group___f_a_p_l.html | |
parent | c5642bdd325aaecbe7da51c4ecb02b2347867560 (diff) | |
download | hdf5-175161c045ec8f1cc69b22030e416b60f40d5343.zip hdf5-175161c045ec8f1cc69b22030e416b60f40d5343.tar.gz hdf5-175161c045ec8f1cc69b22030e416b60f40d5343.tar.bz2 |
deploy: 1706355ee10cdad20b79603b3f39935601c5fff0
Diffstat (limited to 'group___f_a_p_l.html')
-rw-r--r-- | group___f_a_p_l.html | 22 |
1 files changed, 11 insertions, 11 deletions
diff --git a/group___f_a_p_l.html b/group___f_a_p_l.html index ea12a28..7dba584 100644 --- a/group___f_a_p_l.html +++ b/group___f_a_p_l.html @@ -37,7 +37,7 @@ <td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td> <td id="projectalign" style="padding-left: 0.5em;"> <div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a> -  <span id="projectnumber">1.15.0.800edda</span> +  <span id="projectnumber">1.15.0.1706355</span> </div> <div id="projectbrief">API Reference</div> </td> @@ -762,7 +762,7 @@ For optimum performance, the <code>page_size</code> parameter should be a power <tr> <td>Memory </td><td><a class="el" href="_h5_f_dcore_8h.html#ae449696f6b86abcd1120beab21fff76a">H5FD_CORE</a> </td><td>With this driver, an application can work with a file in memory for faster reads and writes. File contents are kept in memory until the file is closed. At closing, the memory version of the file can be written back to disk or abandoned. </td><td><a class="el" href="group___f_a_p_l.html#ga6e6628f620a1c58c704129cf07282849" title="Modifies the file access property list to use the H5FD_CORE driver.">H5Pset_fapl_core()</a> </td></tr> <tr> -<td>Family </td><td><a class="el" href="_h5_f_dfamily_8h.html#adbf24f060712550a2a9649589a6060c6">H5FD_FAMILY</a> </td><td>With this driver, the HDF5 file’s address space is partitioned into pieces and sent to separate storage files using an underlying driver of the user’s choice. This driver is for systems that do not support files larger than 2 gigabytes. </td><td><a class="el" href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53" title="Sets the file access property list to use the family driver.">H5Pset_fapl_family()</a> </td></tr> +<td>Family </td><td><a class="el" href="_h5_f_dfamily_8h.html#adbf24f060712550a2a9649589a6060c6">H5FD_FAMILY</a> </td><td>With this driver, the HDF5 file's address space is partitioned into pieces and sent to separate storage files using an underlying driver of the user's choice. This driver is for systems that do not support files larger than 2 gigabytes. </td><td><a class="el" href="group___f_a_p_l.html#ga95d19da25f196ce1ace10af00f49ab53" title="Sets the file access property list to use the family driver.">H5Pset_fapl_family()</a> </td></tr> <tr> <td>Multi </td><td><a class="el" href="_h5_f_dmulti_8h.html#a754e05ae5e0f2d86f64002b338c0fd5c">H5FD_MULTI</a> </td><td>With this driver, data can be stored in multiple files according to the type of data. I/O might work better if data is stored in separate files based on the type of data. The Split driver is a special case of this driver. </td><td><a class="el" href="group___f_a_p_l.html#ga296bd22cc1e462351f8f0a00a46baf58" title="Sets up use of the multi-file driver.">H5Pset_fapl_multi()</a> </td></tr> <tr> @@ -1626,7 +1626,7 @@ For optimum performance, the <code>page_size</code> parameter should be a power </dl> <dl class="section return"><dt>Returns</dt><dd>Returns a non-negative value if successful; otherwise, returns a negative value.</dd></dl> <p><a class="el" href="group___f_a_p_l.html#ga337626cc516d5d1e3303ea6bc350e56b" title="Retrieves a copy of the file image designated as the initial content and structure of a file.">H5Pget_file_image()</a> allows an application to retrieve a copy of the file image designated for a VFD to use as the initial contents of a file.</p> -<p>If file image callbacks are defined, <a class="el" href="group___f_a_p_l.html#ga337626cc516d5d1e3303ea6bc350e56b" title="Retrieves a copy of the file image designated as the initial content and structure of a file.">H5Pget_file_image()</a> will use them when allocating and loading the buffer to return to the application (see <a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a>). If file image callbacks are not defined, the function will use <code>malloc</code> and <code>memcpy</code>. When <code>malloc</code> and <code>memcpy</code> are used, it is the caller’s responsibility to discard the returned buffer with a call to <code>free</code>.</p> +<p>If file image callbacks are defined, <a class="el" href="group___f_a_p_l.html#ga337626cc516d5d1e3303ea6bc350e56b" title="Retrieves a copy of the file image designated as the initial content and structure of a file.">H5Pget_file_image()</a> will use them when allocating and loading the buffer to return to the application (see <a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a>). If file image callbacks are not defined, the function will use <code>malloc</code> and <code>memcpy</code>. When <code>malloc</code> and <code>memcpy</code> are used, it is the caller's responsibility to discard the returned buffer with a call to <code>free</code>.</p> <p>It is the responsibility of the calling application to free the buffer whose address is returned in <code>buf_ptr_ptr</code>. This can be accomplished with <code>free</code> if file image callbacks have not been set (see <a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a>) or with the appropriate method if file image callbacks have been set.</p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group___h5_l_t.html#ga07fcf2af194e87a3e45252544ebe4aa4" title="Opens an HDF5 file image in memory.">H5LTopen_file_image()</a>, <a class="el" href="group___h5_f.html#gadc53f4e76b1199cb5d2a8cb7fbb114ad" title="Retrieves a copy of the image of an existing, open file.">H5Fget_file_image()</a>, <a class="el" href="group___f_a_p_l.html#ga31d0299f6ad287e013b2a02a8ccc1fa2" title="Sets an initial file image in a memory buffer.">H5Pset_file_image()</a>, <a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a>, <a class="el" href="group___f_a_p_l.html#gae17e38082dfdbadd75c897f1e6a9096e" title="Retrieves callback routines for working with file images.">H5Pget_file_image_callbacks()</a>, <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html">H5FD_file_image_callbacks_t</a>, <a class="el" href="_h5_f_dpublic_8h.html#aa95ee1806ea4db9f035cd53844c008dd">H5FD_file_image_op_t</a>, <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations">HDF5 File Image Operations</a>.</dd></dl> <dl class="section since"><dt>Since</dt><dd>1.8.9 </dd></dl> @@ -2835,8 +2835,8 @@ The H5VL_CAP_FLAG_ASYNC flag can be checked to see if asynchronous operations ar </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>Returns a non-negative value if successful; otherwise, returns a negative value.</dd></dl> -<p><a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache()</a> sets the number of elements, the total number of bytes, and the preemption policy value for all datasets in a file on the file’s file access property list.</p> -<p>The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk’s index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values are determined by the <code>rdcc_nslots</code> parameter. If a different chunk in the cache has the same hash value, a collision will occur, which will reduce efficiency. If inserting the chunk into the cache would cause the cache to be too big, then the cache will be pruned according to the <code>rdcc_w0</code> parameter.</p> +<p><a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache()</a> sets the number of elements, the total number of bytes, and the preemption policy value for all datasets in a file on the file's file access property list.</p> +<p>The raw data chunk cache inserts chunks into the cache by first computing a hash value using the address of a chunk and then by using that hash value as the chunk's index into the table of cached chunks. In other words, the size of this hash table and the number of possible hash values are determined by the <code>rdcc_nslots</code> parameter. If a different chunk in the cache has the same hash value, a collision will occur, which will reduce efficiency. If inserting the chunk into the cache would cause the cache to be too big, then the cache will be pruned according to the <code>rdcc_w0</code> parameter.</p> <p>The <code>mdc_nelmts</code> parameter is no longer used; any value passed in that parameter will be ignored.</p> <p><b>Motivation:</b> Setting raw data chunk cache parameters can be done with <a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache()</a>, <a class="el" href="group___d_a_p_l.html#ga104d00442c31714ee073dee518f661f1" title="Sets the raw data chunk cache parameters.">H5Pset_chunk_cache()</a>, or a combination of both. <a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache()</a> is used to adjust the chunk cache parameters for all datasets via a global setting for the file, and <a class="el" href="group___d_a_p_l.html#ga104d00442c31714ee073dee518f661f1" title="Sets the raw data chunk cache parameters.">H5Pset_chunk_cache()</a> is used to adjust the chunk cache parameters for individual datasets. When both are used, parameters set with <a class="el" href="group___d_a_p_l.html#ga104d00442c31714ee073dee518f661f1" title="Sets the raw data chunk cache parameters.">H5Pset_chunk_cache()</a> will override any parameters set with <a class="el" href="group___f_a_p_l.html#ga034a5fc54d9b05296555544d8dd9fe89" title="Sets the raw data chunk cache parameters.">H5Pset_cache()</a>.</p> <dl class="section note"><dt>Note</dt><dd>Optimum chunk cache parameters may vary widely depending on different data layout and access patterns. For datasets with low performance requirements for example, changing the cache settings can save memory.</dd> @@ -3145,7 +3145,7 @@ Raw dataset chunk caching is supported when these drivers are used in read-only <p>The default external link open file cache size is 0 (zero), meaning that files accessed via an external link are not held open. Setting the cache size to a positive integer turns on the cache; setting the size back to zero turns it off.</p> <p>With this property set, files are placed in the external link open file cache cache when they are opened via an external link. Files are then held open until either they are evicted from the cache or the parent file is closed. This property setting can improve performance when external links are repeatedly accessed.</p> <p>When the cache is full, files will be evicted using a least recently used (LRU) scheme; the file which has gone the longest time without being accessed through the parent file will be evicted and closed if nothing else is holding that file open.</p> -<p>Files opened through external links inherit the parent file’s file access property list by default, and therefore inherit the parent file’s external link open file cache setting.</p> +<p>Files opened through external links inherit the parent file's file access property list by default, and therefore inherit the parent file's external link open file cache setting.</p> <p>When child files contain external links of their own, the caches can form a graph of cached external files. Closing the last external reference to such a graph will recursively close all files in the graph, even if cycles are present. </p><dl class="section user"><dt>Example</dt><dd><p class="startdd">The following code sets up an external link open file cache that will hold open up to 8 files reached through external links:</p> <div class="fragment"><div class="line">status = <a class="code" href="group___f_a_p_l.html#gac21a815e9b133802df625c9f766ef325">H5Pset_elink_file_cache_size</a>(fapl_id, 8);</div> <div class="ttc" id="agroup___f_a_p_l_html_gac21a815e9b133802df625c9f766ef325"><div class="ttname"><a href="group___f_a_p_l.html#gac21a815e9b133802df625c9f766ef325">H5Pset_elink_file_cache_size</a></div><div class="ttdeci">herr_t H5Pset_elink_file_cache_size(hid_t plist_id, unsigned efc_size)</div><div class="ttdoc">Sets the number of files that can be held open in an external link open file cache.</div></div> @@ -3342,9 +3342,9 @@ Raw dataset chunk caching is supported when these drivers are used in read-only </dl> <dl class="section return"><dt>Returns</dt><dd>Returns a non-negative value if successful; otherwise, returns a negative value.</dd></dl> <p><a class="el" href="group___f_a_p_l.html#ga2839252e149484ef30fb214ae7b44ac7" title="Sets up use of the direct I/O driver.">H5Pset_fapl_direct()</a> sets the file access property list, <code>fapl_id</code>, to use the direct I/O driver, <a class="el" href="_h5_f_ddirect_8h.html#a99213f218f9ab0c51f9c679228a1e436">H5FD_DIRECT</a>. With this driver, data is written to or read from the file synchronously without being cached by the system.</p> -<p>File systems usually require the data address in memory, the file address, and the size of the data to be aligned. The HDF5 library’s direct I/O driver is able to handle unaligned data, though that will consume some additional memory resources and may slow performance. To get better performance, use the system function <code>posix_memalign</code> to align the data buffer in memory and the HDF5 function <a class="el" href="group___f_a_p_l.html#gab99d5af749aeb3896fd9e3ceb273677a" title="Sets alignment properties of a file access property list.">H5Pset_alignment()</a> to align the data in the file. Be aware, however, that aligned data I/O may cause the HDF5 file to be bigger than the actual data size would otherwise require because the alignment may leave some holes in the file.</p> +<p>File systems usually require the data address in memory, the file address, and the size of the data to be aligned. The HDF5 library's direct I/O driver is able to handle unaligned data, though that will consume some additional memory resources and may slow performance. To get better performance, use the system function <code>posix_memalign</code> to align the data buffer in memory and the HDF5 function <a class="el" href="group___f_a_p_l.html#gab99d5af749aeb3896fd9e3ceb273677a" title="Sets alignment properties of a file access property list.">H5Pset_alignment()</a> to align the data in the file. Be aware, however, that aligned data I/O may cause the HDF5 file to be bigger than the actual data size would otherwise require because the alignment may leave some holes in the file.</p> <p><code>alignment</code> specifies the required alignment boundary in memory.</p> -<p><code>block_size</code> specifies the file system block size. A value of 0 (zero) means to use HDF5 library’s default value of 4KB.</p> +<p><code>block_size</code> specifies the file system block size. A value of 0 (zero) means to use HDF5 library's default value of 4KB.</p> <p><code>cbuf_size</code> specifies the copy buffer size.</p> <dl class="section since"><dt>Since</dt><dd>1.8.0 </dd></dl> @@ -4268,7 +4268,7 @@ The <code>vfd_config</code> parameter may be NULL. In this case, the reference i <dl class="section return"><dt>Returns</dt><dd>Returns a non-negative value if successful; otherwise, returns a negative value.</dd></dl> <p><a class="el" href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830" title="Sets the Windows I/O driver.">H5Pset_fapl_windows()</a> sets the default HDF5 Windows I/O driver on Windows systems.</p> <p>Since the HDF5 library uses this driver, <a class="el" href="_h5_f_dwindows_8h.html#ab5173993ddefd103bfb3d37c2837a9a4">H5FD_WINDOWS</a>, by default on Windows systems, it is not normally necessary for a user application to call <a class="el" href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830" title="Sets the Windows I/O driver.">H5Pset_fapl_windows()</a>. While it is not recommended, there may be times when a user chooses to set a different HDF5 driver, such as the standard I/O driver (<a class="el" href="_h5_f_dstdio_8h.html#a030a03b96a9f6e46035ce64e25389085">H5FD_STDIO</a>) or the sec2 driver (<a class="el" href="_h5_f_dsec2_8h.html#a15ae1f958e1cf11cb239916d76b10606">H5FD_SEC2</a>), in a Windows application. <a class="el" href="group___f_a_p_l.html#ga0017f78e0f3de465621fde556f679830" title="Sets the Windows I/O driver.">H5Pset_fapl_windows()</a> is provided so that the application can return to the Windows I/O driver when the time comes.</p> -<p>Only the Windows driver is tested on Windows systems; other drivers are used at the application’s and the user’s risk.</p> +<p>Only the Windows driver is tested on Windows systems; other drivers are used at the application's and the user's risk.</p> <p>Furthermore, the Windows driver is tested and available only on Windows systems; it is not available on non-Windows systems.</p> <dl class="section since"><dt>Since</dt><dd>1.8.0 </dd></dl> @@ -4438,7 +4438,7 @@ The <code>vfd_config</code> parameter may be NULL. In this case, the reference i <p><a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a> allows an application to control the management of file image buffers through user defined callbacks. These callbacks can be used in the management of file image buffers in property lists and with certain file drivers.</p> <p><a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a> must be used before any file image has been set in the file access property list. Once a file image has been set, the function will fail.</p> <p>The callback routines set up by <a class="el" href="group___f_a_p_l.html#ga14ea3598215afd078b964b672b40d63c" title="Sets the callbacks for working with file images.">H5Pset_file_image_callbacks()</a> are invoked when a new file image buffer is allocated, when an existing file image buffer is copied or resized, or when a file image buffer is released from use.</p> -<p>Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver’s internal buffer, potentially allowing optimizations such as avoiding large <code>malloc</code> and <code>memcpy</code> operations, or to perform detailed logging.</p> +<p>Some file drivers allow the use of user-defined callback functions for allocating, freeing, and copying the driver's internal buffer, potentially allowing optimizations such as avoiding large <code>malloc</code> and <code>memcpy</code> operations, or to perform detailed logging.</p> <p>From the perspective of the HDF5 library, the operations of the <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#afb936c7647c5704f666d779bbb73b645">image_malloc</a>, <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#aa1a0f08fab985cca0f9b871933e97c97">image_memcpy</a>, <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#a16858b8fdd29678868e3c9294f19d5aa">image_realloc</a>, and <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#a7e81e4662ea07b93e9380f5f78fee890">image_free</a> callbacks must be identical to those of the corresponding C standard library calls (<code>malloc</code>, <code>memcpy</code>, <code>realloc</code>, and <code>free</code>). While the operations must be identical, the file image callbacks have more parameters. The return values of <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#afb936c7647c5704f666d779bbb73b645">image_malloc</a> and <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#a16858b8fdd29678868e3c9294f19d5aa">image_realloc</a> are identical to the return values of <code>malloc</code> and <code>realloc</code>. The return values of <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#afb936c7647c5704f666d779bbb73b645">image_malloc</a> and <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#a7e81e4662ea07b93e9380f5f78fee890">image_free</a> differ from the return values of <code>memcpy</code> and <code>free</code> in that the return values of <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#aa1a0f08fab985cca0f9b871933e97c97">image_memcpy</a> and <a class="el" href="struct_h5_f_d__file__image__callbacks__t.html#a7e81e4662ea07b93e9380f5f78fee890">image_free</a> can also indicate failure.</p> <p>The callbacks and their parameters, along with a struct and an <code>ENUM</code> required for their use, are described below.</p> <p><b>Callback struct and <code>ENUM:</b></code> </p> @@ -5451,7 +5451,7 @@ Failure Modes:<ul> <!-- start footer part --> <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> <ul> - <li class="footer">Generated on Wed Jul 19 2023 00:58:02 for HDF5 by + <li class="footer">Generated on Fri Jul 21 2023 00:33:46 for HDF5 by <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li> </ul> |