Page tree

The license could not be verified: License Certificate has expired!









Sets up Read-Only S3 virtual file driver


H5P_SET_FAPL_ROS3 (fapl_id, fa)


herr_t H5Pset_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa)


hid_t fapl_id                IN: File access property list identifier

H5FD_ros3_fapl_t *fa       IN: Structure containing fapl configuration information


H5P_SET_FAPL_ROS3 sets the file access property list fapl_id to use the ROS3 file driver.

The Read-Only S3 virtual file driver transparently accesses HDF5-format files hosted remotely on Amazon's Simple Storage Service (S3). It supplies bytes transparently to the HDF5 library through the AWS REST API.

In addition to requiring very different underlying operation, files on S3 may have restricted access, requiring that attempts to access and read provide "credentials" to authenticate the recipient and message integrity. The structure H5FD_ros3_fapl_t contains a flag to indicate whether or not this authentication is to take place, as well as to supply credentials to the virtual file driver.

If the configuration structure is set to not authenticate, e.g., fa.authenticate == (hbool_t)FALSE, then the credential fields aws_region, secret_id, and secret_key are ignored.

If the configuration structure is set to authenticate, e.g.,fa.authenticate== (hbool_t)TRUE, then the credential fields must be populated with null-terminated strings. Each component is an array of characters, the size of which is determined by a constant in H5FDros3.c, e.g., H5FD__ROS3_MAX_REGION_LEN. If the string exceeds the defined length, an error has likely occurred and behavior is undefined.


Non-negative value if successful. Otherwise returns negative value.

   hid_t fapl_id = -1;
    /* default, non-authenticating, "anonymous" fapl configuration */
    H5FD_ros3_fapl_t fa = { 1, 0, "", "", "" };
    /* fapl with authentication credentials provided statically */
    fa = { 1,                                         /* version             */
           1,                                         /* authenticate        */
           "us-east-2",                               /* aws_region          */
           "AKIAIMC3D3XLYXLN5COA",                    /* access_key_id       */
           "ugs5aVVnLFCErO/8uW14iWE3K5AgXMpsMlWneO/+" /* secret_access_key   */
    /* fapl populated dynamically
    /* Assumes variables `should_authenticate`, `the_region`,
     * `the_access_key_id`, and `the_secret_access_key` have been set somewhere
    fa.authenticate = should_authenticate; /* 0 (FALSE) or 1 (TRUE) */
    strncpy(fa.aws_region, the_region, H5FD__ROS3_MAX_REGION_LEN);
    strncpy(fa.secret_id, the_access_key_id, H5FD__ROS3_MAX_SECRET_ID_LEN);
    strncpy(fa.secret_key, the_secret_access_key,
    #endif /* set authenticating fapl info statically or dynamically */
    /* create and set fapl entry */
    fapl_id = H5Pcreate(H5P_FILE_ACCESS);
    assert( 0 >= fapl_id );
    assert( 0 >= H5Pset_fapl_ros3(fapl_id, &fa) );


Release    Change
1.10.6C function introduced in this release.

--- Last Modified: February 10, 2020 | 01:20 PM