3 Example Programs

Before describing the individual CFITSIO routines in detail, it is instructive to first look at an actual program. The names of the CFITSIO routines are fairly descriptive (they all begin with fits_, so it should be reasonably clear what this program does:

----------------------------------------------------------------
    #include <string.h>
    #include <stdio.h>
1:  #include "fitsio.h"

    int main(int argc, char *argv[])
    {
2:      fitsfile *fptr;         
        char card[FLEN_CARD]; 
3:      int status = 0,  nkeys, ii;  /* MUST initialize status */

4:      fits_open_file(&fptr, argv[1], READONLY, &status);
        fits_get_hdrspace(fptr, &nkeys, NULL, &status);

        for (ii = 1; ii <= nkeys; ii++)  { 
          fits_read_record(fptr, ii, card, &status); /* read keyword */
          printf("%s\n", card);
        }
        printf("END\n\n");  /* terminate listing with END */
        fits_close_file(fptr, &status);

        if (status)          /* print any error messages */
5:          fits_report_error(stderr, status);
        return(status);
    }
----------------------------------------------------------------

This program opens the specified FITS file and prints out all the header keywords in the current HDU. Some other points to notice about the program are:

1. The fitsio.h header file must be included to define the various routines and symbols used in CFITSIO.

2. The fitsfile parameter is the first argument in almost every CFITSIO routine. It is a pointer to a structure (defined in fitsio.h) that stores information about the particular FITS file that the routine will operate on. Memory for this structure is automatically allocated when the file is first opened or created, and is freed when the file is closed.

3. Almost every CFITSIO routine has a status parameter as the last argument. The status value is also usually returned as the value of the function itself. Normally status = 0, and a positive status value indicates an error of some sort. The status variable must always be initialized to zero before use, because if status is greater than zero on input then the CFITSIO routines will simply return without doing anything. This `inherited status' feature, where each CFITSIO routine inherits the status from the previous routine, makes it unnecessary to check the status value after every single CFITSIO routine call. Generally you should check the status after an especially important or complicated routine has been called, or after a block of closely related CFITSIO calls. This example program has taken this feature to the extreme and only checks the status value at the very end of the program.

4. In this example program the file name to be opened is given as an argument on the command line (arg[1]). If the file contains more than 1 HDU or extension, you can specify which particular HDU to be opened by enclosing the name or number of the HDU in square brackets following the root name of the file. For example, file.fts[0] opens the primary array, while file.fts[2] will move to and open the 2nd extension in the file, and file.fit[EVENTS] will open the extension that has a EXTNAME = 'EVENTS' keyword in the header. Note that on the Unix command line you must enclose the file name in single or double quote characters if the name contains special characters such as `[' or `]'.

   All of the CFITSIO routines which read or write header keywords, image data, or table data operate only within the currently opened HDU in the file. To read or write information in a different HDU you must first explicitly move to that HDU (see the fits_movabs_hdu and fits_movrel_hdu routines in section 4.3).

5. The fits_report_error routine provides a convenient way to print out diagnostic messages about any error that may have occurred.

A set of example FITS utility programs are available from the CFITSIO web site at
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/cexamples.html. These are real working programs which illustrate how to read, write, and modify FITS files using the CFITSIO library. Most of these programs are very short, containing only a few 10s of lines of executable code or less, yet they perform quite useful operations on FITS files. Running each program without any command line arguments will produce a short description of how to use the program. The currently available programs are:

fitscopy - copy a file
listhead - list header keywords
liststruc - show the structure of a FITS file.
modhead - write or modify a header keyword
imarith - add, subtract, multiply, or divide 2 images
imlist - list pixel values in an image
imstat - compute mean, min, and max pixel values in an image
tablist - display the contents of a FITS table
tabcalc - general table calculator