4.3 Function Names and Variable Datatypes

Most of the CFITSIO routines have both a short name as well as a longer descriptive name. The short name is only 5 or 6 characters long and is similar to the subroutine name in the Fortran-77 version of FITSIO. The longer name is more descriptive and it is recommended that it be used instead of the short name to more clearly document the source code.

Many of the CFITSIO routines come in families which differ only in the datatype of the associated parameter(s). The datatype of these routines is indicated by the suffix of the routine name. The short routine names have a 1 or 2 character suffix (e.g., 'j' in 'ffpkyj') while the long routine names have a 4 character or longer suffix as shown in the following table:

    Long      Short  Data
    Names     Names  Type
    -----     -----  ----
    _bit        x    bit
    _byt        b    unsigned byte
    _sht        i    short integer
    _lng        j    long integer
    _lnglng     jj   8-byte LONGLONG integer (see note below)
    _usht       ui   unsigned short integer
    _ulng       uj   unsigned long integer
    _uint       uk   unsigned int integer
    _int        k    int integer
    _flt        e    real exponential floating point (float)
    _fixflt     f    real fixed-decimal format floating point (float)
    _dbl        d    double precision real floating-point (double)
    _fixdbl     g    double precision fixed-format floating point (double)
    _cmp        c    complex reals (pairs of float values)
    _fixcmp     fc   complex reals, fixed-format floating point
    _dblcmp     m    double precision complex (pairs of double values)
    _fixdblcmp  fm   double precision complex, fixed-format floating point
    _log        l    logical (int)
    _str        s    character string

The logical datatype corresponds to `int' for logical keyword values, and `byte' for logical binary table columns. In other words, the value when writing a logical keyword must be stored in an `int' variable, and must be stored in a `char' array when reading or writing to `L' columns in a binary table. Inplicit data type conversion is not supported for logical table columns, but is for keywords, so a logical keyword may be read and cast to any numerical data type; a returned value = 0 indicates false, and any other value = true.

The `int' datatype may be 2 bytes long on some IBM PC compatible systems and is usually 4 bytes long on most other systems. Some 64-bit machines, however, like the Dec Alpha/OSF, define the `short', `int', and `long' integer datatypes to be 2, 4, and 8 bytes long, respectively. The FITS standard only supports 2 and 4 byte integer data types, so CFITSIO internally converts between 4 and 8 bytes when reading or writing `long' integers on Alpha/OSF systems.

The 8-byte 'LONGLONG' integer datatype is supported on most platforms. CFITSIO defines the LONGLONG datatype to be equivalent to 'long long' on most Unix platforms and on Mac OS-X. Since most Windows compilers don't support the 'long long' datatype, LONGLONG is defined instead to be equivalent to '__int64'. If the compiler does not support a 8-byte integer datatype then LONGLONG is defined to be equivalent to 'long'. Note that the C format specifier to print out these long integer values is "%lld" on most unix machines, except on OSF platforms where "%ld" must be used. On Windows platform which have the __int64 data type, the format specifier is "%INT64d".

When dealing with the FITS byte datatype it is important to remember that the raw values (before any scaling by the BSCALE and BZERO, or TSCALn and TZEROn keyword values) in byte arrays (BITPIX = 8) or byte columns (TFORMn = 'B') are interpreted as unsigned bytes with values ranging from 0 to 255. Some C compilers define a 'char' variable as signed, so it is important to explicitly declare a numeric char variable as 'unsigned char' to avoid any ambiguity

One feature of the CFITSIO routines is that they can operate on a `X' (bit) column in a binary table as though it were a `B' (byte) column. For example a `11X' datatype column can be interpreted the same as a `2B' column (i.e., 2 unsigned 8-bit bytes). In some instances, it can be more efficient to read and write whole bytes at a time, rather than reading or writing each individual bit.

The complex and double precision complex datatypes are not directly supported in ANSI C so these datatypes should be interpreted as pairs of float or double values, respectively, where the first value in each pair is the real part, and the second is the imaginary part.