How do you work with a file created with the file family feature?

The file family feature is specified as a File Access Property List. The Property List topic in the HDF5 Tutorial talks about this feature.

To access a file with the file family feature, when you open or create the file, the name of it should include a printf integer format specifier (which gets replaced with the family member number). For example, junk%d.h5 would result in files, such as, junk0.h5, junk1.h5, junk2.h5 ...

There are some problems with the file family feature with the 5-1.6* (and earlier) releases.

Right now, if you are going to use the file family feature, we recommend that when you read the file, you know that it was created with the file family feature and what the file member size is. Also, you must have written enough data to the file when you created it, to fill up the first file member. Otherwise, HDF5 will re-set the file member size to the size of the data that was written.

Here is an example of how you would read a file that was created using the file family feature:

  ...
  #define FILE "junk%d.h5"

  main() {

    hid_t       file_id, fapl;
    hsize_t     msize;
    herr_t      status;

    fapl = H5Pcreate (H5P_FILE_ACCESS);
    msize = 1024*1024;
    status = H5Pset_fapl_family (fapl, msize, H5P_DEFAULT);
    file_id = H5Fopen(FILE, H5F_ACC_RDWR, fapl);
    ...

As you can see above, it requires you to know ahead of time that the files were created with the file family feature, and what the file member size is. In actuality, for read-only, the size you specify doesn't matter. That's why h5dump and h5ls can read the file. (You can change 'msize' to 1 in the code above and it works!)

However, if you open the file using the wrong file member size, and try to *write* data to the file, it may not work as expected.

The problems with the file family feature will be fixed in a future release.