Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Single Writer Multiple Readers
Files (H5F)

## Detailed Description

## Functions
herr_t | H5Fget_metadata_read_retry_info (hid_t file_id, H5F_retry_info_t *info)
| Retrieves the collection of read retries for metadata entries with checksum.
herr_t | H5Fstart_swmr_write (hid_t file_id)
| Retrieves free-space section information for a file.

## Function Documentation

## ◆ H5Fget_metadata_read_retry_info()

herr_t H5Fget_metadata_read_retry_info | ( | hid_t | file_id,
|  | H5F_retry_info_t * | info )

Retrieves the collection of read retries for metadata entries with checksum.

Parameters

  [in] | file_id | File identifier
  [out] | info | Struct containing the collection of read retries for metadata entries with checksum

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

Failure Modes:

- When the input identifier is not a file identifier.
- When the pointer to the output structure is NULL.
- When the memory allocation for `retries` failed.

H5Fget_metadata_read_retry_info() retrieves information regarding the number of read retries for metadata entries with checksum for the file `file_id`. This information is reported in the H5F_retry_info_t struct defined in H5Fpublic.h as follows:

#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
typedef struct H5F_retry_info_t {
unsigned nbins;
uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
} H5F_retry_info_t;

`nbins` is the number of bins for each `retries`[i] of metadata entry `i`. It is calculated based on the current number of read attempts used in the library and logarithmic base 10.

If read retries are incurred for a metadata entry `i`, the library will allocate memory for retries[i] (nbins * sizeof(uint32_t) and store the collection of retries there. If there are no retries for a metadata entry `i`, retries[i] will be NULL. After a call to this routine, users should free each retries[i] that is non-NULL, otherwise resource leak will occur.

For the library default read attempts of 100 for SWMR access, nbins will be 2 as depicted below:

- retries[i][0] is the number of 1 to 9 read retries.
- retries[i][1] is the number of 10 to 99 read retries. For the library default read attempts of 1 for non-SWMR access, `nbins` will be 0 and each retries[i] will be NULL.

The following table lists the 21 metadata entries of retries[]:

Index for retries[] | Metadata entries*
--- | ---
0 | Object header (version 2)
1 | Object header chunk (version 2)
2 | B-tree header (version 2)
3 | B-tree internal node (version 2)
4 | B-tree leaf node (version 2)
5 | Fractal heap header
6 | Fractal heap direct block (optional checksum)
7 | Fractal heap indirect block
8 | Free-space header
9 | Free-space sections
10 | Shared object header message table
11 | Shared message record list
12 | Extensive array header
13 | Extensive array index block
14 | Extensive array super block
15 | Extensive array data block
16 | Extensive array data block page
17 | Fixed array super block
18 | Fixed array data block
19 | Fixed array data block page
20 | File's superblock (version 2)
* All entries are of version 0 (zero) unless indicated otherwise.

Note
  On a system that is not atomic, the library might possibly read inconsistent metadata with checksum when performing single-writer/multiple-reader (SWMR) operations for an HDF5 file. Upon encountering such situations, the library will try reading the metadata again for a set number of times to attempt to obtain consistent data. The maximum number of read attempts used by the library will be either the value set via H5Pset_metadata_read_attempts() or the library default value when a value is not set.
  When the current number of metadata read attempts used in the library is unable to remedy the reading of inconsistent metadata on a system, the user can assess the information obtained via this routine to derive a different maximum value. The information can also be helpful for debugging purposes to identify potential issues with metadata flush dependencies and SWMR implementation in general.

Since
  1.10.0

## ◆ H5Fstart_swmr_write()

herr_t H5Fstart_swmr_write | ( | hid_t | file_id | ) |

Retrieves free-space section information for a file.

Parameters

  [in] | file_id | File identifier

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5Fstart_swmr_write() will activate SWMR writing mode for a file associated with `file_id`. This routine will prepare and ensure the file is safe for SWMR writing as follows:

- Check that the file is opened with write access (H5F_ACC_RDWR).
- Check that the file is opened with the latest library format to ensure data structures with check-summed metadata are used.
- Check that the file is not already marked in SWMR writing mode.
- Enable reading retries for check-summed metadata to remedy possible checksum failures from reading inconsistent metadata on a system that is not atomic.
- Turn off usage of the library's accumulator to avoid possible ordering problem on a system that is not atomic.
- Perform a flush of the file's data buffers and metadata to set a consistent state for starting SWMR write operations.

Library objects are groups, datasets, and committed datatypes. For the current implementation, groups and datasets can remain open when activating SWMR writing mode, but not committed datatypes. Attributes attached to objects cannot remain open either.

Since
  1.10.0