next up previous contents Back To Software Index
Next: FITS File Open Up: No Title Previous: Data I/O Routines

Advanced Interface Routines

This chapter defines all the available routines in the CFITSIO user interface. For completeness, the basic routines described in the previous chapter are also repeated here. Refer to Chapter 9 for the definition of all the parameters.

The following conventions are used in this chapter:

1. Each routine has 2 names: a long descriptive name and a short concise name. Both names are listed on the first line of the following descriptions, separated by a slash (/) character.

2. A right arrow symbol (>) is used to separate the input parameters from the output parameters in the definition of each routine. This symbol is not actually part of the C calling sequence. Note that the status parameter is both an input and an output parameter.

3. Families of similar routines which differ only in the datatype of the argument(s) are defined together using a convention of listing the last letter(s) of the routine names in square brackets. For example, the routines for reading data from a primary array are defined as:

  int ffgpv[b,i,ui,j,uj,k,e,d](fitsfile *fptr, long group, long firstelem,
           long nelements, DTYPE nulval, > DTYPE *array, int *anynul,
           int *status)
This is a short-hand notation for indicating that there are 8 separate routines, ffgpvb, ffgpvi, ffgpvui, ffgpvj, ffgpvuj, ffgpvk, ffgpve, and ffgpvd, which have different datatypes for the nulval and array arguments.

4. A datatype specification of `DTYPE' is used to indicate that the parameter has a numerical datatype which depends on the last letter(s) of the routine's short name as given by the following table:

      Name     Data
      suffix   type
      ----     --------
        b   -  unsigned char
        l   -  int (logical value)
        i   -  short integer
        j   -  long integer
       ui   -  unsigned short integer
       uj   -  unsigned long integer
        k   -  int integer
     e, f   -  float
     d, g   -  double
        c   -  pairs of floats (complex value)
        m   -  pairs of doubles (complex value)
Thus, in the previous example the `nulval' and `array' parameters have a short int datatype in the ffgpvi routine and have a double datatype in the ffgpvd routine.