Last modified: 28 February 2014
Name: H5Pget_metadata_read_attempts
Signature:
  `herr_t H5Pget_metadata_read_attempts( hid_t plist_id, unsigned *attempts )`
Purpose:
  Retrieves the number of read attempts from a file access property list.
Motivation:
  See the description in `H5Pset_metadata_read_attempts`.
Description:
  `H5Pget_metadata_read_attempts` retrieves the number of read attempts that is set in the file access property list `plist_id`.

  For a default file access property list, the value retrieved will depend on whether the user sets the number of attempts via `H5Pset_metadata_read_attempts`:

  - If the number of attempts is set to N, the value returned will be N.
  - If the number of attempts is not set, the value returned will be the default for non-SWMR access (1). SWMR is short for single-writer/multiple-reader.

  For the file access property list of a specified HDF5 file, the value retrieved will depend on how the file is opened and whether the user sets the number of read attempts via `H5Pset_metadata_read_attempts`:

  - For a file opened with SWMR access:
    - If the number of attempts is set to N, the value returned will be N.
    - If the number of attempts is not set, the value returned will be the default for SWMR access (100).
  - For a file opened without SWMR access, the value retrieved will always be the default for non-SWMR access (1). The value set via `H5Pset_metadata_read_attempts` does not have any effect on non-SWMR access.
Parameters:

  `hid_t plist_id` | IN: Identifier for a file access property list.
  `unsigned *attempts` | OUT: The number of read attempts.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Failure Modes:
  When the input property list is not a file access property list.

  When the library is unable to retrieve the number of read attempts from the file access property list.

Example Usage:
  The first example illustrates the two cases for retrieving the number of read attempts from a default file access property list.

          /* Get a copy of file access property list */
          fapl = H5Pcreate(H5P_FILE_ACCESS);

          /* Retrieve the # of read attempts from the file access property list */
          H5Pget_metadata_read_attempts(fapl, &attempts);

          /*
           *  The value returned in "attempts" will be 1 (default for non-SWMR access).
           */

          /* Set the # of read attempts to 20 */
          H5Pset_metadata_read_attempts(fapl, 20);

          /* Retrieve the # of read attempts from the file access property list */
          H5Pget_metadata_read_attempts(fapl, &attempts);

          /*
           *  The value returned in "attempts" will be 20 as set.
           */

          /* Close the property list */
          H5Pclose(fapl);

  The second example illustrates the two cases for retrieving the number of read attempts from the file access property list of a file opened with SWMR acccess.

          /* Open the file with SWMR access and default file access property list */
          fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), H5P_DEFAULT);

          /* Get the file's file access roperty list */
          file_fapl = H5Fget_access_plist(fid);

          /* Retrieve the # of read attempts from the file's file access property list */
          H5Pget_metadata_read_attempts(file_fapl, &attempts);

          /*
           *  The value returned in "attempts" will be 100 (default for SWMR access).
           */

          /* Close the property list */
          H5Pclose(file_fapl);

          /* Close the file */
          H5Fclose(fid);

          /* Create a copy of file access property list */
          fapl = H5Pcreate(H5P_FILE_ACCESS);

          /* Set the # of read attempts */
          H5Pset_metadata_read_attempts(fapl, 20);

          /* Open the file with SWMR access and the non-default file access property list */
          fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl);

          /* Get the file's file access roperty list */
          file_fapl = H5Fget_access_plist(fid);

          /* Retrieve the # of read attempts from the file's file access property list */
          H5Pget_metadata_read_attempts(file_fapl, &attempts);

          /*
           *  The value returned in "attempts" will be 20.
           */

          /* Close the property lists */
          H5Pclose(file_fapl);
          H5Pclose(fapl);

          /* Close the file */
          H5Fclose(fid);

  The third example illustrates the two cases for retrieving the number of read attempts from the file access property list of a file opened with non-SWMR acccess.

          /* Open the file with non-SWMR access and default file access property list */
          fid = H5Fopen(FILE, H5F_ACC_RDONLY, H5P_DEFAULT);

          /* Get the file's file access roperty list */
          file_fapl = H5Fget_access_plist(fid);

          /* Retrieve the # of read attempts from the file's file access property list */
          H5Pget_metadata_read_attempts(file_fapl, &attempts);

          /*
           *  The value returned in "attempts" will be 1 (default for non-SWMR access).
           */

          /* Close the property list */
          H5Pclose(file_fapl);

          /* Close the file */
          H5Fclose(fid);

          /* Create a copy of file access property list */
          fapl = H5Pcreate(H5P_FILE_ACCESS);

          /* Set the # of read attempts */
          H5Pset_metadata_read_attempts(fapl, 20);

          /* Open the file with non-SWMR access and the non-default file access property list */
          fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl);

          /* Get the file's file access roperty list */
          file_fapl = H5Fget_access_plist(fid);

          /* Retrieve the # of read attempts from the file's file access property list */
          H5Pget_metadata_read_attempts(file_fapl, &attempts);

          /*
           *  The value returned in "attempts" will be 1 (default for non-SWMR access).
           */

          /* Close the property lists */
          H5Pclose(file_fapl);
          H5Pclose(fapl);

          /* Close the file */
          H5Fclose(fid);

Fortran Interface:
  None
See Also:
  - `H5Pset_metadata_read_attempts`
  - `H5Fget_metadata_read_retries_info`
History:

  Release | Change
  1.10.0 | C function introduced with this release.