FITS File Open and Close Routines

Application programs must first declare a pointer to a structure of type 'fitsfile' for each FITS file that is opened. The fitsfile structure is created and initialize by the call to open or create the FITS file and then the pointer to the structure must be passed as the first argument to all the other CFITSIO routines that read or write to the FITS file. This structure is used to hold internal parameters about the FITS file. The memory that is allocated for the fitsfile structure is freed when the FITS file is closed.

1

Open an existing FITS file with readonly or readwrite access. The iomode parameter has allowed symbolic constant values of READONLY or READWRITE. If the filename = "-" then CFITSIO will read the FITS file from the stdin file stream rather than from a disk file. If the file to be opened resides in memory (see fits_set_mem_buff, below) then a null file name may be given to indicate that the file already exists in memory; otherwise the specified diskfile (or the stdin stream if the file name = "-") will be copied into memory and all subsequent operations on the file will take place on the memory copy of the file. Note that any modifications to the memory file do not automatically get copied back to the disk file in this case.

  int fits_open_file / ffopen
      (fitsfile **fptr, char *filename, int iomode, > int *status)

2

Create and initialize a new empty FITS file. If the filename = "-" then the file will be written to the stdout file stream rather than to magnetic disk. (The file is actually created in memory and flushed to the stdout stream when the FITS file is closed). If a memory buffer has been allocated for the file (see fits_set_mem_buff, below) then the file name is ignored unless it is '-' in which case the memroy file is copied to the stdout stream when the file is closed.

  int fits_create_file / ffinit
      (fitsfile **fptr, char *filename, > int *status)

3

Flush any internal buffers of data to the output FITS file. This routine rarely needs to be called, but can be useful when writing to the FITS files in memory, and will ensure that if the program subsequently aborts then the FITS file will have been closed properly.

  int fits_flush_file / ffflus
      (fitsfile *fptr, > int *status)

4

Close a previously opened FITS file. If the file resides in a user-allocated memory buffer (see fits_set_mem_buff, below) then the memory buffer is left unchanged and the application program must free the memory when it is no longer needed.

  int fits_close_file / ffclos
      (fitsfile *fptr, > int *status)

5

Close and DELETE a FITS disk file previously opened with ffopen or ffinit. This routine may be useful in cases where a FITS file is created but then an error occurs which prevents the file from being completed.

  int fits_delete_file / ffdelt
      (fitsfile *fptr, > int *status)

6

Initialize a memory buffer to be used for reading or writing a FITS file in computer memory. This routine must be called before calling fits_open_file or fits_create_file to tell CFITSIO that the file will reside in memory instead of on magnetic disk, thus causing all subsequent CFITSIO routine calls to operate on the file in memory. In general, the application must preallocate an initial block of memory to hold the FITS file: 'memptr' points to the starting address and 'mem_size' gives the initial size of the block of memory. 'Mem_realloc' is a pointer to an optional function that CFITSIO can call to allocate additional memory, if needed, and is modeled after the standard C 'realloc' function; a null pointer may be given if the initial allocation of memory is all that will be required. The 'delta_size' parameter may be used to suggest a minimum amount of additional memory that should be allocated during each call to the memory reallocation function. By default, CFITSIO will reallocate enough additional space to hold the entire currently defined FITS file (as given by the NAXISn keywords) or 1 FITS block (= 2880 bytes), whichever is larger. Values of delta_size less than 2880 will be ignored. Since the memory reallocation operation can be computationally expensive, allocating a larger initial block of memory, and/or specifying a larger delta_size value may help to reduce the number of reallocation calls and make the application program run faster. This routine returns a special status value which must be passed on as input to the fits_open_file or fits_create_file routine. It is not necessary to call this routine if one is simply reading a file from the stdin stream, or writing to the stdout stream (by specifying a file name = "-"). The 'testmem.c' program that is included with the CFITSIO distribution provides an example of how to use this routine.

  int fits_set_mem_buff / ffsbuf
      (fitsfile **fptr, void **memptr, size_t *mem_size, size_t delta_size,
       void *(*mem_realloc)(void *p, int newsize), > int *status);

7

Copy a FITS file residing in memory (see fits_set_mem_buff) out to a diskfile. The memory may be copied out to the 'stdout' stream by giving a filename = "-". The 'mem_size' parameter specifies the maximum size of the file which may be greater than the actual file size.

  int fits_write_mem_buff / ffwbuf
      (void *memptr, size_t mem_size, char *filename, > int *status)