CFITSIO Interface Routines

                        January 1997

CFITSIO is a library of ANSI C routines for reading and writing FITS
format files.  The design of these C routines closely follows the
Fortran subroutines provided in the original fitsio library.  The
CFITSIO User's Guide, in the file cfitsio.ps (postscript format) or
cfitsio.doc (plain ASCII text) contains full instructions on building
and using this library.

This new CFITSIO library, written entirely in ANSI C, should not be
confused with the previously available set of C macros which provide a
C-callable interface to the Fortran fitsio routines.  These older
macros which are no longer being supported, are contained in the
cfitsio.h file that is distributed along with the Fortran fitsio source
files.

BUILDING CFITSIO
----------------

The CFITSIO code is contained in about 30 *.c source files and 3 *.h
header files.  The CFITSIO library is built on Unix systems by typing:

>  configure
>  make

at the operating system prompt.  The 'configure' command customizes
the Makefile for your particular system, then the 'make' command
builds the library.

On VAX/VMS and ALPHA/VMS systems, the make.com command file may be
used to build the cfitsio.olb object library.  Execute this command
file by typing '@make' on the command line.

On DOS-based PC computers, the makepc.bat file gives an example of how
to build the CFITSIO library.  This file will probably need to be
editted to include the appropriate command switches if a different C
compiler or linker is used.

On OS/2 systems, CFITSIO can be built using the supplied
makefile by typing 'make -f makefile.os2'.
This makefile requires the GCC compiler and EMX library,
which are available from many Internet sites containing OS/2
software, such as ftp-os2.nmsu.edu/pub/os2/dev/emx/v0.9c
and ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc.

The MacOS version of the cfitsio library can be built by (1) unbinhex
and unstuff cfitsio_mac.sit.hqx, and (2) for the PPC,  load CFitsio
PPCLibrary.(pi) into CodeWarrior 10+ and make.  This builds the cfitsio
library for PPC.  If you would like to build the test program, load
CFitsio PPC testprog.(pi) into CodeWarrior 10+ and make.

TESTING CFITSIO
---------------

The CFITSIO library should be tested by building and running
the testprog.c program that is included with the release. 
On Unix systems (assuming the gcc compiler is being used), type:
-
    % gcc -o testprog testprog.c -L. -lcfitsio -lm
    % testprog > testprog.lis
    % diff testprog.lis testprog.out
    % cmp testprog.fit testprog.std
-
 On VMS systems,
(assuming cc is the name of the C compiler command), type:
-
    $ cc testprog.c
    $ link testprog, cfitsio/lib
    $ run testprog
-
The testprog program should produce a FITS file called `testprog.fit'
that is identical to the testprog.std FITS file included in this
release.  The diagnostic messages (which were piped to the file
testprog.lis in the Unix example) should be identical to the listing
contained in the file testprog.out.  The 'diff' and 'cmp' commands
shown above should not report any differences in the files.

USING CFITSIO
-------------

The CFITSIO User's Guide, contained in the files cfitsio.doc (plain
text file) and cfitsio.ps (postscript file), provides detailed
documentation about how to build and use the CFITSIO library.
It contains a description of every user-callable routine in the
CFITSIO interface.

The cookbook.c file provides some sample routines for performing common
operations on various types of FITS files.  Programmers are urged to
examine these routines for recommended programming practices when using
CFITSIO.  Users are free to copy or modify these routines for their own
purposes.

SUPPORTED PLATFORMS
-------------------

CFITSIO has currently been tested on the following platforms:

   Operating System          Compiler
   ----------------          --------
   Sun OS                     gcc and cc (3.0.1)
   Sun Solaris                gcc and cc
   Silicon Graphics IRIX      gcc and cc
   DECstation  Ultrix         gcc
   Dec Alpha OSF/1            gcc
   Dec Alpha OpenVMS          cc with /float=gfloat or /float=ieee options
   DEC VAX/VMS                gcc and cc
   Linux running on IBM PC    gcc
   IBM PC w/ Windows 95       Borland C++ V4.5
   IBM PC w/ OS/2             gcc + EMX
   MacOS 7.1 or greater       Metrowerks 10.+

CFITSIO will probably run on most other Unix platforms without
modification.  Cray supercomputers and IBM mainframe computers are
currently not supported.

Reports of any success or failure to run CFITSIO on other platforms
would be appreciated.  Any problem reports or suggestions for
improvements are also welcome.  Please send any reports to the author
at:   pence@tetra.gsfc.nasa.gov

-------------------------------------------------------------------------
William D. Pence
HEASARC, NASA/GSFC