FITS File Access Routines

These routines will open or close a new or existing FITS file or return information about the opened FITS file. These routines support the extended file name syntax that is described in a previous chapter.

The same FITS file may be opened more than once simultaneously and the resulting pointers to the files may be treated as though they were completely independent FITS files. Thus, one could open a FITS file twice, move to different extensions within the file, and then read or write data to the 2 extensions in any order.

1

Open an existing FITS file with a specified access mode. The iomode parameter may have a value of READONLY or READWRITE.  

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

2

Reopen a FITS file that was previously opened with fits_open_file or fits_create_file. The new fitsfile pointer may then be treated as a separate file, and one may simultaneously read or write to 2 (or more) different extensions in the same file. The fits_open_file routine (above) automatically detects cases where a previously opened file is being opened again, and then internally call fits_reopen_file, so programs should rarely need to explicitly call this routine.  

  int fits_reopen_file / ffreopen
      (fitsfile *openfptr, fitsfile **newfptr, > int *status)

3

Create a new empty FITS file. An error will be returned if the specified file already exists unless the filename is prefixed with an exclamation point (!). In that case CFITSIO will overwrite the existing file.  

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

4

Create a new FITS file, using a template file to define its initial size and structure. The template may be another FITS HDU or an ASCII template file. If the input template file name pointer is null, then this routine behaves the same as fits_create_file. The currently supported format of the ASCII template file is described under the fits_parse_template routine (in the general Utilities section), but this may change slightly in the full v2.0 release of CFITSIO.  

  int fits_create_template / fftplt
      (fitsfile **fptr, char *filename, char *tpltfile > int *status)

5

Close a previously opened FITS file.  

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

6

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)

7

Return the name of the opened FITS file.  

  int fits_file_name / ffflnm
      (fitsfile *fptr, > char *filename, int *status)

8

Return the I/O mode of the open FITS file (READONLY or READWRITE).  

  int fits_file_mode / ffflmd
      (fitsfile *fptr, > int *iomode, int *status)

9

Return the file type of the opened FITS file (e.g. 'file://', 'ftp://', etc.).  

  int fits_url_type / ffurlt
      (fitsfile *fptr, > char *urltype, int *status)

10

Parse the input filename or URL into its component parts: the file type (file://, ftp://, http://, etc), the base input file name, the name of the output file that the input file is to be copied to prior to opening, the HDU or extension specification, the filtering specifier, the binning specifier, and the column specifier. Null strings will be returned for any components that are not present in the input file name.  

  int fits_parse_input_url / ffiurl
      (char *filename, > char *filetype, char *infile, char *outfile, char
       *extspec, char *filter, char *binspec, char *colspec, int *status)

11

Parse the input filename and return the HDU number that would be moved to if the file were opened with fits_open_file. The returned HDU number begins with 1 for the primary array, so for example, if the input filename = `myfile.fits[2]' then hdunum = 3 will be returned. If an extension name is included in the file name specification (e.g. `myfile.fits[EVENTS]' then this routine will have to open the FITS file and look for the position of the named extension, then close file. This is not possible if the file is being read from the stdin stream, and an error will be returned in this case. If the filename does not specify an explicit extension (e.g. 'myfile.fits') then hdunum = -99 will be returned, which is functionally equivalent to hdunum = 1. This routine is mainly used for backward compatibility in the ftools software package and is not recommended for general use. It is generally better and more efficient to first open the FITS file with fits_open_file, then use fits_get_hdu_num to determine which HDU in the file has been opened, rather than calling fits_parse_input_url then calling fits_open_file.  

   int fits_parse_extnum / ffextn (char *filename, > int *hdunum)

12

Parse the input file name and return the root file name. The root name includes the file type if specified, (e.g. 'ftp://' or 'http://') and the full path name, to the extent that it is specified in the input filename. It does not enclude the HDU name or number, or any filtering specifications.  

   int fits_parse_rootname / ffrtnm
       (char *filename, > char *rootname, int *status);