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:
- The fitsio.h header file must be included to define the
various routines and symbols used in CFITSIO.
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.
- 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.
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).
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