�������� ���� �� ���� ��������� ������. ����� ������������� ��������� : http://vega.inp.nsk.su/~inest/OCAAS/cfitsio.ps ���� ���������: Wed Mar 29 15:29:00 2000 ���� ��������������: Mon Oct 1 19:54:11 2012 ���������: ��������� �����: � � � � � � � � � � � � � �

CFITSIO User's Guide
An Interface to FITS Format Files
for C Programmers
Version 2.0
HEASARC
Code 662
Goddard Space Flight Center
Greenbelt, MD 20771
USA
February 2000


Contents
1 Introduction 1
2 Creating the CFITSIO Library 3
2.1 Building the Library : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 3
2.1.1 Unix Systems : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 3
2.1.2 VMS : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5
2.1.3 Windows PCs : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5
2.1.4 OS/2 : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5
2.1.5 Macintosh PCs : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 5
2.2 Testing the Library : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 6
2.3 Linking Programs with CFITSIO : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 7
2.4 Getting Started with CFITSIO : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 7
2.5 Example Program : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 8
2.6 Acknowledgements : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 9
3 A FITS Primer 11
4 Extended File Name Syntax 13
4.1 Overview : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 13
4.2 Detailed Filename Syntax : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 15
4.2.1 Filetype : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 16
4.2.2 Base Filename : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 19
4.2.3 Output File Name when Opening an Existing File : : : : : : : : : : : : : : : 20
4.2.4 Template File Name when Creating a New File : : : : : : : : : : : : : : : : : 21
4.2.5 HDU Location Specification : : : : : : : : : : : : : : : : : : : : : : : : : : : : 25
i

ii CONTENTS
4.2.6 Image Section : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 26
4.2.7 Column and Keyword Filtering Specification : : : : : : : : : : : : : : : : : : 27
4.2.8 Row Filtering Specification : : : : : : : : : : : : : : : : : : : : : : : : : : : : 28
4.2.9 Binning or Histogramming Specification : : : : : : : : : : : : : : : : : : : : : 35
5 CFITSIO Conventions and Guidelines 39
5.1 CFITSIO Definitions : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 39
5.2 CFITSIO Size Limitations : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 41
5.3 Multiple Access to the Same FITS File : : : : : : : : : : : : : : : : : : : : : : : : : : 42
5.4 Current Header Data Unit (CHDU) : : : : : : : : : : : : : : : : : : : : : : : : : : : 42
5.5 Function Names and Datatypes : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 42
5.6 Unsigned Integers : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 44
5.7 Character Strings : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 46
5.8 Implicit Data Type Conversion : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 47
5.9 Data Scaling : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 47
5.10 Error Status Values and the Error Message Stack : : : : : : : : : : : : : : : : : : : : 47
5.11 Variable�Length Arrays in Binary Tables : : : : : : : : : : : : : : : : : : : : : : : : : 48
5.12 Support for IEEE Special Values : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 50
5.13 When the Final Size of the FITS HDU is Unknown : : : : : : : : : : : : : : : : : : : 50
5.14 Local FITS Conventions supported by CFITSIO : : : : : : : : : : : : : : : : : : : : 51
5.14.1 Long String Keyword Values. : : : : : : : : : : : : : : : : : : : : : : : : : : : 51
5.14.2 Arrays of Fixed�Length Strings in Binary Tables : : : : : : : : : : : : : : : : 52
5.14.3 Keyword Units Strings : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 52
5.14.4 HIERARCH Convention for Extended Keyword Names : : : : : : : : : : : : 53
5.15 Optimizing Code for Maximum Processing Speed : : : : : : : : : : : : : : : : : : : : 54
5.15.1 Background Information: How CFITSIO Manages Data I/O : : : : : : : : : 54
5.15.2 Optimization Strategies : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 55
6 The CFITSIO Iterator Function 59
6.1 The Iterator Work Function : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 60
6.2 The Iterator Driver Function : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 62
6.3 Guidelines for Using the Iterator Function : : : : : : : : : : : : : : : : : : : : : : : : 63

CONTENTS iii
7 Basic CFITSIO Interface Routines 65
7.1 CFITSIO Error Status Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 65
7.2 FITS File Access Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 66
7.3 HDU Access Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 69
7.4 Header Keyword Read/Write Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 71
7.5 Iterator Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 74
7.6 Primary Array or IMAGE Extension I/O Routines : : : : : : : : : : : : : : : : : : : 76
7.7 ASCII and Binary Table Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : 77
7.7.1 Column Information Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 78
7.7.2 Routines to Edit Rows or Columns : : : : : : : : : : : : : : : : : : : : : : : 80
7.7.3 Read and Write Column Data Routines : : : : : : : : : : : : : : : : : : : : : 81
7.8 Celestial Coordinate System Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 83
7.8.1 Self�contained WCS Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 84
7.8.2 WCS Routines that require the WCS library : : : : : : : : : : : : : : : : : : 85
7.9 Hierarchical Grouping Convention Support Routines : : : : : : : : : : : : : : : : : : 87
7.10 Row Selection and Calculator Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 92
7.11 File Checksum Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 93
7.12 Date and Time Utility Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 95
7.13 General Utility Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 96
8 Specialized CFITSIO Interface Routines 103
8.1 Specialized FITS File Access Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 103
8.2 Specialized HDU Access Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 104
8.3 Specialized Header Keyword Routines : : : : : : : : : : : : : : : : : : : : : : : : : : 106
8.3.1 Header Information Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : 106
8.3.2 Read and Write the Required Keywords : : : : : : : : : : : : : : : : : : : : : 106
8.3.3 Specialized Write Keyword Routines : : : : : : : : : : : : : : : : : : : : : : : 108
8.3.4 Insert Keyword Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : : 110
8.3.5 Specialized Read Keyword Routines : : : : : : : : : : : : : : : : : : : : : : : 111
8.3.6 Modify Keyword Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : : 113
8.3.7 Specialized Update Keyword Routines : : : : : : : : : : : : : : : : : : : : : 114
8.4 Define Data Scaling and Undefined Pixel Parameters : : : : : : : : : : : : : : : : : : 114

iv CONTENTS
8.5 Specialized FITS Primary Array or IMAGE Extension I/O Routines : : : : : : : : : 116
8.6 Specialized FITS ASCII and Binary Table Routines : : : : : : : : : : : : : : : : : : 119
8.6.1 Column Information Routines : : : : : : : : : : : : : : : : : : : : : : : : : : : 119
8.6.2 Low�Level Table Access Routines : : : : : : : : : : : : : : : : : : : : : : : : 120
8.6.3 Specialized Write Column Data Routines : : : : : : : : : : : : : : : : : : : : 121
8.6.4 Specialized Read Column Data Routines : : : : : : : : : : : : : : : : : : : : : 122
A Index of Routines 127
B Parameter Definitions 131
C CFITSIO Error Status Codes 137

Chapter 1
Introduction
CFITSIO is a machine�independent library of routines for reading and writing data files in the
FITS (Flexible Image Transport System) data format. It can also read IRAF format image files
by converting them on the fly into a temporary FITS format file. This library is written in ANSI
C and provides a powerful yet simple interface for accessing FITS files which will run on most
commonly used computers and workstations. CFITSIO supports all the features described in the
official NOST definition of the FITS format and can read and write all the currently defined types
of extensions, including ASCII tables (TABLE), Binary tables (BINTABLE) and IMAGE exten�
sions. The CFITSIO routines insulate the programmer from having to deal with the complicated
formatting details in the FITS file, however, it is assumed that users have a general knowledge
about the structure and usage of FITS files.
CFITSIO also contains a set of Fortran callable wrapper routines which allow Fortran programs
to call the CFITSIO routines. See the companion ``FITSIO User's Guide'' for the definition of the
Fortran subroutine calling sequences. These wrappers replace the older Fortran FITSIO library
which is no longer supported.
The CFITSIO package was initially developed by the HEASARC (High Energy Astrophysics Science
Archive Research Center) at the NASA Goddard Space Flight Center to convert various existing
and newly acquired astronomical data sets into FITS format and to further analyze data already in
FITS format. New features continue to be added to CFITSIO in large part due to contributions of
ideas or actual code from users of the package. The Integral Science Data Center in Switzerland,
and the XMM/ESTEC project in The Netherlands made especially significant contributions that
resulted in many of the new features that appeared in v2.0 of CFITSIO.
The latest version of the CFITSIO source code, documentation, and example programs are available
on the World�Wide Web or via anonymous ftp from:
http://heasarc.gsfc.nasa.gov/fitsio
ftp://legacy.gsfc.nasa.gov/software/fitsio/c
Any questions, bug reports, or suggested enhancements related to the CFITSIO package should be
sent to the primary author:
1

2 CHAPTER 1. INTRODUCTION
Dr. William Pence Telephone: (301) 286�4599
HEASARC, Code 662 E�mail: pence@tetra.gsfc.nasa.gov
NASA/Goddard Space Flight Center
Greenbelt, MD 20771, USA
This User's Guide assumes that readers already have a general understanding of the definition and
structure of FITS format files. Further information about FITS formats is available in the `FITS
User's Guide' and the `NOST FITS Standard', which are available from the NASA Science Office
of Standards and Technology at the address given below. Both of these documents are available
electronically from their Web site and via anonymous ftp at nssdc.gsfc.nasa.gov in the /pub/fits
directory. Any questions about FITS formats should be directed to the NOST, at:
NASA, Science Office of Standards and Technology
Code 633.2,
Goddard Space Flight Center
Greenbelt MD 20771, USA
WWW: http://www.gsfc.nasa.gov/astro/fits/fits�home.html
E�mail: fits@nssdca.gsfc.nasa.gov
(301) 286�2899
CFITSIO users may also be interested in the FTOOLS package of programs that can be used to
manipulate and analyze FITS format files. Information about FTOOLS can be obtained on the
Web or via anonymous ftp at:
http://heasarc.gsfc.nasa.gov/ftools
ftp://legacy.gsfc.nasa.gov/software/ftools/release

Chapter 2
Creating the CFITSIO Library
2.1 Building the Library
The CFITSIO code is contained in about 40 C source files (*.c) and header files (*.h). On
VAX/VMS systems 2 assembly�code files (vmsieeed.mar and vmsieeer.mar) are also needed.
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
Dec Alpha OSF/1 gcc and cc
DECstation Ultrix gcc
Dec Alpha OpenVMS cc
DEC VAX/VMS gcc and cc
HP�UX gcc
IBM AIX gcc
Linux gcc
MkLinux DR3
Windows 95/98 Borland C++ V4.5
Windows NT Microsoft Visual C++ v5.0, v6.0
OS/2 gcc + EMX
MacOS 7.1 or greater Metrowerks 10.+
CFITSIO will probably run on most other Unix platforms. Cray supercomputers and IBM main�
frame computers are currently not supported.
2.1.1 Unix Systems
The CFITSIO library is built on Unix systems by typing:
3

4 CHAPTER 2. CREATING THE CFITSIO LIBRARY
? ./configure
? make
at the operating system prompt. Type ./configure and not simply `configure' to ensure that the
configure script in the current directory is run and not some other system�wide configure script. The
configure command customizes the Makefile for the particular system, then the `make' command
compiles the source files and builds the library.
On HP/UX systems, the environment variable CFLAGS should be set to �Ae before running con�
figure to enable ''extended ANSI'' features.
By default, a set of Fortran�callable wrapper routines are also built and included in the CFITSIO
library. If these wrapper routines are not needed (i.e., the CFITSIO library will not be linked
to any Fortran applications which call FITSIO subroutines) then they may be omitted from the
build by typing 'make all�nofitsio' instead of simply typing 'make'. This will reduce the size of the
CFITSIO library slightly.
It may not be possible to staticly link programs that use CFITSIO on some platforms (namely,
on Solaris 2.6) due to the network drivers (which provide FTP and HTTP access to FITS files).
It is possible to make both a dynamic and a static version of the CFITSIO library, but network
file access will not be possible using the static version. To build the dynamic libcfitsio.so library
(on solaris), type 'make clean', then edit the Makefile to add �fPIC or �KPIC (gcc or cc) to the
CFLAGS line, then rebuild the library with 'make'. Once you're done, build the shared library
with
ld �G �z text �o libcfitsio.so *.o
Then to get the staticly linkable libcfitsio.a library file do another make clean, undefine HAVE NET SERVICES
on the CFLAGS line and rebuild. It's unimportant whether or not you use �fPIC for static builds.
When using the shared library the executable code is not copied into your program at link time and
instead the program locates the necessary library code at run time, normally through LD LIBRARY PATH
or some other method. The advantages are:
1. Less disk space if you build more than 1 program
2. Less memory if more than one copy of a program using the shared
library is running at the same time since the system is smart
enough to share copies of the shared library at run time.
3. Possibly easier maintenance since a new version of the shared
library can be installed without relinking all the software
that uses it (as long as the subroutine names and calling
sequences remain unchanged).
4. No run�time penalty.
The disadvantages are:

2.1. BUILDING THE LIBRARY 5
1. More hassle at runtime. You have to either build the programs
specially or have LD�LIBRARY�PATH set right.
2. There may be a slight start up penality, depending on where you are
reading the shared library and the program from and if your CPU is
either really slow or really heavily loaded.
2.1.2 VMS
On VAX/VMS and ALPHA/VMS systems the make.com command file may be used to build
the cfitsio.olb object library using the default G�floating point option for double variables. The
make dfloat.com and make ieee.com files may be used instead to build the library with the other
floating point options. Note that the getcwd function that is used in the group.c module may require
that programs using CFITSIO be linked with the ALPHA$LIBRARY:VAXCRTL.OLB library. See
the example link line in the next section of this document.
2.1.3 Windows PCs
A precompiled DLL version of CFITSIO is available for IBM�PC users in the file cfitsio dll.zip.
This zip archive also contains other files and instructions on how to use the CFITSIO DLL library.
The CFITSIO library may be built using a suitable compiler. The makepc.bat file gives an example
of how to build CFITSIO with the Borland C++ v4.5 compiler. This file will probably need to
be edited to include the appropriate command switches if a different C compiler or linker is used.
The files cfitsio.dsp, cfitsio.dsw, and cookbook.dsp contain the Microsoft Developer workspace files
for building CFITSIO and the cookbook example program on WindowsNT using Microsoft Visual
C++ 5.0 or 6.0.
2.1.4 OS/2
On OS/2 systems, CFITSIO can be built 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.
2.1.5 Macintosh PCs
The MacOS version of the CFITSIO library can be built by (1) un binhex and unstuff cfit�
sio mac.sit.hqx, (2) put CFitsioPPC.mcp in the cfitsio directory, and (3) load CFitsioPPC.mcp
into CodeWarrior Pro 2 and make. This builds the cfitsio library for PPC. There are also targets
for both the test program and the speed test program.

6 CHAPTER 2. CREATING THE CFITSIO LIBRARY
To use the MacOS port you can add Cfitsio PPC.lib to your CodeWarrior Pro 2 project. Note that
this only has been tested for the PPC and probably won't work on 68k Macs.
2.2 Testing the Library
The CFITSIO library should be tested by building and running the testprog.c program that is
included with the release. On Unix systems, type:
% make testprog
% 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, alpha$library:vaxcrtl/lib
$ run testprog
The testprog program should produce a FITS file called `testprog.fit' that is identical to the `test�
prog.std' FITS file included with 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. (There
may be some minor formating differences, such as the presence or absence of leading zeros, or 3
digit exponents in numbers, which can be ignored).
The Fortran wrappers in CFITSIO may be tested with the testf77 program on Unix systems with:
% f77 �o testf77 testf77.f �L. �lcfitsio �lnsl �lsocket
or
% f77 �f �o testf77 testf77.f �L. �lcfitsio (under SUN O/S)
or
% f77 �o testf77 testf77.f �Wl,�L. �lcfitsio �lm �lnsl �lsocket (HP/UX)
% testf77 ? testf77.lis
% diff testf77.lis testf77.out
% cmp testf77.fit testf77.std
On machines running SUN O/S, Fortran programs must be compiled with the '�f' option to force
double precision variables to be aligned on 8�byte boundarys to make the fortran�declared variables
compatible with C. A similar compiler option may be required on other platforms. Failing to use
this option may cause the program to crash on FITSIO routines that read or write double precision
variables.

2.3. LINKING PROGRAMS WITH CFITSIO 7
Also note that on some systems, the output listing of the testf77 program may differ slightly from
the testf77.std template, if leading zeros are not printed by default before the decimal point when
using F format.
A few other utility programs are included with CFITSIO:
speed � measures the maximum throughput (in MB per second)
for writing and reading FITS files with CFITSIO.
listhead � lists all the header keywords in any FITS file
fitscopy � copies any FITS file (especially useful in conjunction
with the CFITSIO's extended input filename syntax).
cookbook � a sample program that peforms common read and
write operations on a FITS file.
iter�a, iter�b, iter�c � tests of the CFITSIO iterator routine
The first 4 of these utility programs can be compiled and linked by typing
% make program�name
2.3 Linking Programs with CFITSIO
When linking applications software with the CFITSIO library, several system libraries usually need
to be specified on the link comma Unix systems, the most reliable way to determine what libraries
are required is to type 'make testprog' and see what libraries the configure script has added. The
typical libraries that need to be added are �lm (the math library) and �lnsl and �lsocket (needed
only for FTP and HTTP file access). These latter 2 libraries are not needed on VMS and Windows
platforms, because FTP file access is not currently supported on those platforms.
Note that when upgrading to a newer version of CFITSIO it is usually necessay to recompile, as
well as relink, the programs that use CFITSIO, because the definitions in fitsio.h often change.
2.4 Getting Started with CFITSIO
In order to effectively use the CFITSIO library as quickly as possible, it is recommended that new
users follow these steps:
1. Read the following `FITS Primer' chapter for an overview of the structure of FITS files. This is
especially important for users who are unfamiliar with the FITS table and image extensions.
2. Review the various topics discussed in Chapters 4 and 5 to become familiar with the conventions
and advanced features of the CFITSIO interface.

8 CHAPTER 2. CREATING THE CFITSIO LIBRARY
3. Refer to the cookbook.c, listhead.c, and fitscopy.c programs that are included with this re�
lease for examples of routines that perform various common FITS file operations. Type 'make
program name' to compile and link these programs on Unix systems.
4. Write a simple program to read or write a FITS file using the Basic Interface routines described
in Chapter 7.
5. Scan through the more specialized routines that are described in Chapter 8 to become familiar
with the functionality that they provide.
2.5 Example Program
The following listing shows an example of how to use the CFITSIO routines in a C program. The
error checking of the returned status value has been omitted for the sake of clarity. Refer to the
cookbook.c program that is included with the CFITSIO distribution for other example programs.
This program creates a new FITS file, containing a FITS image. An `EXPOSURE' keyword is
written to the header, then the image data are writen to the FITS file before closing the FITS file.
#include ''fitsio.h'' /* required by every program that uses CFITSIO */
main()
--
fitsfile *fptr; /* pointer to the FITS file; defined in fitsio.h */
int status, ii, jj;
long fpixel = 1, naxis = 2, nelements, exposure;
long naxes[2] = -- 300, 200 �; /* image is 300 pixels wide by 200 rows */
short array[200][300];
status = 0; /* initialize status before calling fitsio routines */
fits�create�file(&fptr, ''testfile.fits'', &status); /* create new file */
/* Create the primary array image (16�bit short integer pixels */
fits�create�img(fptr, SHORT�IMG, naxis, naxes, &status);
/* Write a keyword; must pass the ADDRESS of the value */
exposure = 1500.;
fits�update�key(fptr, TLONG, ''EXPOSURE'', &exposure,
''Total Exposure Time'', &status);
/* Initialize the values in the image with a linear ramp function */
for (jj = 0; jj ! naxes[1]; jj++)
for (ii = 0; ii ! naxes[0]; ii++)
array[jj][ii] = ii + jj;
nelements = naxes[0] * naxes[1]; /* number of pixels to write */

2.6. ACKNOWLEDGEMENTS 9
/* Write the array of integers to the image */
fits�write�img(fptr, TSHORT, fpixel, nelements, array[0], &status);
fits�close�file(fptr, &status); /* close the file */
fits�report�error(stderr, status); /* print out any error messages */
return( status );
�
2.6 Acknowledgements
The development of many of the powerful features in CFITSIO was made possible through collab�
orations with many people or organizations from around the world. The following, in particular,
have made especially significant contributions:
Programmers from the Integral Science Data Center, Switzerland (namely, Jurek Borkowski, Bruce
O'Neel, and Don Jennings), designed the concept for the plug�in I/O drivers that was introduced
with CFITSIO 2.0. The use of `drivers' greatly simplified the low�level I/O, which in turn made
other new features in CFITSIO (e.g., support for compressed FITS files and support for IRAF
format image files) much easier to implement. Jurek Borkowski wrote the Shared Memory driver,
and Bruce O'Neel wrote the drivers for accessing FITS files over the network using the FTP, HTTP,
and ROOT protocols.
The ISDC also provided the template parsing routines (written by Jurek Borkowski) and the
hierarchical grouping routines (written by Don Jennings). The ISDC DAL (Data Access Layer)
routines are layered on top of CFITSIO and make extensive use of these features.
Uwe Lammers (XMM/ESA/ESTEC, The Netherlands) designed the high�performance lexical pars�
ing algorithm that is used to do on�the�fly filtering of FITS tables. This algorithm essentially
pre�compiles the user�supplied selection expression into a form that can be rapidly evaluated for
each row. Peter Wilson (RSTX, NASA/GSFC) then wrote the parsing routines used by CFITSIO
based on Lammers' design, combined with other techniques such as the CFITSIO iterator routine
to further enhance the data processing throughput. This effort also benefitted from a much earlier
lexical parsing routine that was developed by Kent Blackburn (NASA/GSFC).
The CFITSIO iterator function is loosely based on similar ideas developed for the XMM Data
Access Layer.
Peter Wilson (RSTX, NASA/GSFC) wrote the complete set of Fortran�callable wrappers for all the
CFITSIO routines, which in turn rely on the CFORTRAN macro developed by Burkhard Burow.
The syntax used by CFITSIO for filtering or binning input FITS files is based on ideas developed
for the AXAF Science Center Data Model by Jonathan McDowell, Antonella Fruscione, Aneta
Siemiginowska and Bill Joye. See http://heasarc.gsfc.nasa.gov/docs/journal/axaf7.html for further
description of the AXAF Data Model.
The file decompression code were taken directly from the gzip (GNU zip) program developed by
Jean�loup Gailly and others.

10 CHAPTER 2. CREATING THE CFITSIO LIBRARY
Doug Mink, SAO, provided the routines for converting IRAF format images into FITS format.
In addition, many other people have made valuable contributions to the development of CFITSIO.
These include (with apologies to others that may have inadvertently been omitted):
Steve Allen, Carl Akerlof, Keith Arnaud, Morten Krabbe Barfoed, Kent Blackburn, G Bodammer,
Romke Bontekoe, Lucio Chiappetti, Keith Costorf, Robin Corbet, John Davis, Richard Fink, Ning
Gan, Emily Greene, Gretchen Green, Joe Harrington, Cheng Ho, Phil Hodge, Jim Ingham, Yoshi�
taka Ishisaki, Diab Jerius, Mark Levine, Todd Karakaskian, Edward King, Scott Koch, Claire
Larkin, Rob Managan, Eric Mandel, John Mattox, Carsten Meyer, Emi Miyata, Stefan Mochnacki,
Mike Noble, Oliver Oberdorf, Clive Page, Arvind Parmar, Jeff Pedelty, Tim Pearson, Maren
Purves, Scott Randall, Chris Rogers, Arnold Rots, Barry Schlesinger, Robin Stebbins, Andrew
Szymkowiak, Allyn Tennant, Peter Teuben, James Theiler, Doug Tody, Shiro Ueno, Steve Wal�
ton, Archie Warnock, Alan Watson, Dan Whipple, Wim Wimmers, Peter Young, Jianjun Xu, and
Nelson Zarate.

Chapter 3
A FITS Primer
This section gives a brief overview of the structure of FITS files. Users should refer to the documen�
tation available from the NOST, as described in the introduction, for more detailed information on
FITS formats.
FITS was first developed in the late 1970's as a standard data interchange format between various
astronomical observatories. Since then FITS has become the standard data format supported by
most astronomical data analysis software packages.
A FITS file consists of one or more Header + Data Units (HDUs), where the first HDU is called
the `Primary HDU', or `Primary Array'. The primary array contains an N�dimensional array of
pixels, such as a 1�D spectrum, a 2�D image, or a 3�D data cube. Five different primary datatypes
are supported: Unsigned 8�bit bytes, 16 and 32�bit signed integers, and 32 and 64�bit floating point
reals. FITS also has a convention for storing 16 and 32�bit unsigned integers (see the later section
entitled `Unsigned Integers' for more details). The primary HDU may also consist of only a header
with a null array containing no data pixels.
Any number of additional HDUs may follow the primary array; these additional HDUs are called
FITS `extensions'. There are currently 3 types of extensions defined by the FITS standard:
ffl Image Extension � a N�dimensional array of pixels, like in a primary array
ffl ASCII Table Extension � rows and columns of data in ASCII character format
ffl Binary Table Extension � rows and columns of data in binary representation
In each case the HDU consists of an ASCII Header Unit followed by an optional Data Unit. For
historical reasons, each Header or Data unit must be an exact multiple of 2880 8�bit bytes long.
Any unused space is padded with fill characters (ASCII blanks or NULs depending on the type of
unit).
Each Header Unit consists of any number of 80�character keyword records or `card images' (reminis�
cent of the 80�column punched cards which were prevalent when the FITS standard was developed)
which have the general form:
11

12 CHAPTER 3. A FITS PRIMER
KEYNAME = value / comment string
NULLKEY = / comment: This keyword has no value
The keyword names may be up to 8 characters long and can only contain uppercase letters, the
digits 0�9, the hyphen, and the underscore character. The keyword name is (usually) fo