4.11 Multiple Access to the Same FITS File

CFITSIO supports simultaneous read and write access to different HDUs in the same FITS file in some circumstances, as described below:

• Multi-threaded programs

  When CFITSIO is compiled with the -D_REENTRANT directive (as can be tested with the fits_is_reentrant function) different threads can call any of the CFITSIO routines to simultaneously read or write separate FITS files. Multiple threads can also read data from the same FITS file simultaneously, as long as the file was opened independently by each thread. This relies on the operating system to correctly deal with reading the same file by multiple processes. Different threads should not share the same 'fitsfile' pointer to read an opened FITS file, unless locks are placed around the calls to the CFITSIO reading routines. Different threads should never try to write to the same FITS file.

• Multiple read access to the same FITS file within a single program/thread

  A single process may open the same FITS file with READONLY access multiple times, and thus create multiple 'fitsfile*' pointers to that same file within CFITSIO. This relies on the operating system's ability to open a single file multiple times and correctly manage the subsequent read requests directed to the different C 'file*' pointers, which actually all point to the same file. CFITSIO simply executes the read requests to the differnet 'fitsfile*' pointers the same as if they were physically different files.

• Multiple write access to the same FITS file within a single program/thread

  CFITSIO supports opening the same FITS file multiple times with WRITE access, but it only physically opens the file (at the operating system level) once, on the first call to fits_open_file. If fits_open_file is subsequently called to open the same file again, CFITSIO will recognize that the file is already open, and will return a new 'fitsfile*' pointer that logically points to the first 'fitsfile*' pointer, without actually opening the file a second time. The application program can then treat the 2 'fitsfile*' pointers as if they point to different files, and can seemingly move to and write data to 2 different HDUs within the same file. However, each time the application program switches which 'fitsfile*' pointer it is writing to, CFITSIO will flush any internal buffers that contain data written to the first 'fitsfile*' pointer, then move to the HDU that the other 'fitsfile*' pointer is writing to. Obviously, this may add a significant amount of computational overhead if the application program uses this feature to frequently switch back and forth between writing to 2 (or more) HDUs in the same file, so this capability should be used judiciously.

  Note that CFITSIO will not allow a FITS file to be opened a second time with READWRITE access if it was opened previously with READONLY access.