Äîêóìåíò âçÿò èç êýøà ïîèñêîâîé ìàøèíû. Àäðåñ îðèãèíàëüíîãî äîêóìåíòà : http://www.astro.louisville.edu/software/sbig/archive/xmccd-4.1/xmccd-4.1e/libcfitsio/libcfitsio-3.310/cfitsio.ps Äàòà èçìåíåíèÿ: Wed Jul 18 21:52:52 2012 Äàòà èíäåêñèðîâàíèÿ: Thu Feb 27 22:51:06 2014 Êîäèðîâêà: Ïîèñêîâûå ñëîâà: ï ï ï ï ï ð ï ð ï ð ï ð ï ð ï ð ï ð ï ð ï ð ï ð ï ï ð ï ï ð ï ï ð ï ï ð ï ï ð ï

CFITSIO User's Reference Guide
An Interface to FITS Format Files
for C Programmers
Version 3.3
HEASARC
Code 662
Goddard Space Flight Center
Greenbelt, MD 20771
USA
April 2012

ii

Contents
1 Introduction 1
1.1 A Brief Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Sources of FITS Software and Information . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.4 Legal Stu# . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Creating the CFITSIO Library 5
2.1 Building the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1 Unix Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.2 VMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.3 Windows PCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.4 Macintosh PCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Testing the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Linking Programs with CFITSIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 Using CFITSIO in Multi­threaded Environments . . . . . . . . . . . . . . . . . . . . 9
2.5 Getting Started with CFITSIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.6 Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3 A FITS Primer 13
4 Programming Guidelines 15
4.1 CFITSIO Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Current Header Data Unit (CHDU) . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3 Function Names and Variable Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4 Support for Unsigned Integers and Signed Bytes . . . . . . . . . . . . . . . . . . . . 20
4.5 Dealing with Character Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
iii

iv CONTENTS
4.6 Implicit Data Type Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.7 Data Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.8 Support for IEEE Special Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.9 Error Status Values and the Error Message Stack . . . . . . . . . . . . . . . . . . . . 24
4.10 Variable­Length Arrays in Binary Tables . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.11 Multiple Access to the Same FITS File . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.12 When the Final Size of the FITS HDU is Unknown . . . . . . . . . . . . . . . . . . . 27
4.13 CFITSIO Size Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5 Basic CFITSIO Interface Routines 29
5.1 CFITSIO Error Status Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.2 FITS File Access Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.3 HDU Access Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.4 Header Keyword Read/Write Routines . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.4.1 Keyword Reading Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.4.2 Keyword Writing Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.5 Primary Array or IMAGE Extension I/O Routines . . . . . . . . . . . . . . . . . . . 40
5.6 Image Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.7 ASCII and Binary Table Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.7.1 Create New Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.7.2 Column Information Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.7.3 Routines to Edit Rows or Columns . . . . . . . . . . . . . . . . . . . . . . . . 52
5.7.4 Read and Write Column Data Routines . . . . . . . . . . . . . . . . . . . . . 53
5.7.5 Row Selection and Calculator Routines . . . . . . . . . . . . . . . . . . . . . 56
5.7.6 Column Binning or Histogramming Routines . . . . . . . . . . . . . . . . . . 57
5.8 Utility Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.8.1 File Checksum Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.8.2 Date and Time Utility Routines . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.8.3 General Utility Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6 The CFITSIO Iterator Function 73
6.1 The Iterator Work Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.2 The Iterator Driver Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.3 Guidelines for Using the Iterator Function . . . . . . . . . . . . . . . . . . . . . . . . 77

CONTENTS v
6.4 Complete List of Iterator Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7 World Coordinate System Routines 81
7.1 Self­contained WCS Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
8 Hierarchical Grouping Routines 85
8.1 Grouping Table Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
8.2 Group Member Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9 Specialized CFITSIO Interface Routines 91
9.1 FITS File Access Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
9.2 HDU Access Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
9.3 Specialized Header Keyword Routines . . . . . . . . . . . . . . . . . . . . . . . . . . 97
9.3.1 Header Information Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
9.3.2 Read and Write the Required Keywords . . . . . . . . . . . . . . . . . . . . . 97
9.3.3 Write Keyword Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.3.4 Insert Keyword Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9.3.5 Read Keyword Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
9.3.6 Modify Keyword Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
9.3.7 Update Keyword Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
9.4 Define Data Scaling and Undefined Pixel Parameters . . . . . . . . . . . . . . . . . . 106
9.5 Specialized FITS Primary Array or IMAGE Extension I/O Routines . . . . . . . . . 107
9.6 Specialized FITS ASCII and Binary Table Routines . . . . . . . . . . . . . . . . . . 110
9.6.1 General Column Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.6.2 Low­Level Table Access Routines . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.6.3 Write Column Data Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.6.4 Read Column Data Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
10 Extended File Name Syntax 117
10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
10.2 Filetype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
10.2.1 Notes about HTTP proxy servers . . . . . . . . . . . . . . . . . . . . . . . . . 120
10.2.2 Notes about the stream filetype driver . . . . . . . . . . . . . . . . . . . . . . 121
10.2.3 Notes about the gsiftp filetype . . . . . . . . . . . . . . . . . . . . . . . . . . 122

vi CONTENTS
10.2.4 Notes about the root filetype . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
10.2.5 Notes about the shmem filetype: . . . . . . . . . . . . . . . . . . . . . . . . . 124
10.3 Base Filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
10.4 Output File Name when Opening an Existing File . . . . . . . . . . . . . . . . . . . 126
10.5 Template File Name when Creating a New File . . . . . . . . . . . . . . . . . . . . . 128
10.6 Image Tile­Compression Specification . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.7 HDU Location Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.8 Image Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
10.9 Image Transform Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10.10Column and Keyword Filtering Specification . . . . . . . . . . . . . . . . . . . . . . 132
10.11Row Filtering Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
10.11.1 General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
10.11.2 Bit Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
10.11.3 Vector Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
10.11.4 Good Time Interval Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
10.11.5 Spatial Region Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
10.11.6 Example Row Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
10.12 Binning or Histogramming Specification . . . . . . . . . . . . . . . . . . . . . . . . . 144
11 Template Files 147
11.1 Detailed Template Line Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.2 Auto­indexing of Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
11.3 Template Parser Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.4 Formal Template Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.5 Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
12 Local FITS Conventions 153
12.1 64­Bit Long Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
12.2 Long String Keyword Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
12.3 Arrays of Fixed­Length Strings in Binary Tables . . . . . . . . . . . . . . . . . . . . 155
12.4 Keyword Units Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
12.5 HIERARCH Convention for Extended Keyword Names . . . . . . . . . . . . . . . . 156
12.6 Tile­Compressed Image Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

CONTENTS vii
13 Optimizing Programs 159
13.1 How CFITSIO Manages Data I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
13.2 Optimization Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
A Index of Routines 165
B Parameter Definitions 171
C CFITSIO Error Status Codes 177

viii CONTENTS

Chapter 1
Introduction
1.1 A Brief Overview
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
and raw binary data arrays by converting them on the fly into a virtual 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 o#cial 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 extensions. 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.
1.2 Sources of FITS Software and Information
The latest version of the CFITSIO source code, documentation, and example programs are available
on the World­Wide Web or via anonymous ftp from:
1

2 CHAPTER 1. INTRODUCTION
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:
Dr. William Pence Telephone: (301) 286­4599
HEASARC, Code 662 E­mail: William.D.Pence@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 from the
FITS Support O#ce at http://fits.gsfc.nasa.gov. In particular, the 'NOST FITS Standard'
gives the authoritative definition of the FITS data format, and the `FITS User's Guide' provides
additional historical background and practical advice on using FITS files.
The HEASARC also provides a very sophisticated FITS file analysis program called `Fv' which
can be used to display and edit the contents of any FITS file as well as construct new FITS files
from scratch. The display functions in Fv allow users to interactively adjust the brightness and
contrast of images, pan, zoom, and blink images, and measure the positions and brightnesses of
objects within images. FITS tables can be displayed like a spread sheet, and then modified using
powerful calculator and sorting functions. Fv is freely available for most Unix platforms, Mac PCs,
and Windows PCs. CFITSIO users may also be interested in the FTOOLS package of programs
that can be used to manipulate and analyze FITS format files. Fv and FTOOLS are available from
their respective Web sites at:
http://fv.gsfc.nasa.gov
http://heasarc.gsfc.nasa.gov/ftools
1.3 Acknowledgments
The development of the many powerful features in CFITSIO was made possible through collabora­
tions 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. Also, in 2009, Bruce O'Neel was the key developer of the thread­safe version
of CFITSIO.

1.3. ACKNOWLEDGMENTS 3
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.
Giuliano Ta#oni and Andrea Barisani, at INAF, University of Trieste, Italy, implemented the I/O
driver routines for accessing FITS files on the computational grids using the gridftp protocol.
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 e#ort also benefited from a much earlier
lexical parsing routine that was developed by Kent Blackburn (NASA/GSFC). More recently, Craig
Markwardt (NASA/GSFC) implemented additional functions (median, average, stddev) and other
enhancements to the lexical parser.
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.
The new compressed image data format (where the image is tiled and the compressed byte stream
from each tile is stored in a binary table) was implemented in collaboration with Richard White
(STScI), Perry Greenfield (STScI) and Doug Tody (NOAO).
Doug Mink (SAO) provided the routines for converting IRAF format images into FITS format.
Martin Reinecke (Max Planck Institute, Garching)) provided the modifications to cfortran.h that
are necessary to support 64­bit integer values when calling C routines from fortran programs. The
cfortran.h macros were originally developed by Burkhard Burow (CERN).
Julian Taylor (ESO, Garching) provided the fast byte­swapping algorithms that use the SSE2 and
SSSE3 machine instructions available on x86 64 CPUs.
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, Richard Mathar, John Mattox, Carsten Meyer, Emi Miyata,
Stefan Mochnacki, Mike Noble, Oliver Oberdorf, Clive Page, Arvind Parmar, Je# Pedelty, Tim

4 CHAPTER 1. INTRODUCTION
Pearson, Philippe Prugniel, Maren Purves, Scott Randall, Chris Rogers, Arnold Rots, Rob Sea­
man, Barry Schlesinger, Robin Stebbins, Andrew Szymkowiak, Allyn Tennant, Peter Teuben, James
Theiler, Doug Tody, Shiro Ueno, Steve Walton, Archie Warnock, Alan Watson, Dan Whipple, Wim
Wimmers, Peter Young, Jianjun Xu, and Nelson Zarate.
1.4 Legal Stu#
Copyright (Unpublished--all rights reserved under the copyright laws of the United States), U.S.
Government as represented by the Administrator of the National Aeronautics and Space Adminis­
tration. No copyright is claimed in the United States under Title 17, U.S. Code.
Permission to freely use, copy, modify, and distribute this software and its documentation without
fee is hereby granted, provided that this copyright notice and disclaimer of warranty appears in all
copies.
DISCLAIMER:
THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND, EI­
THER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO,
ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR­
POSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE DOC­
UMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE
SOFTWARE WILL BE ERROR FREE. IN NO EVENT SHALL NASA BE LIABLE FOR ANY
DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR CON­
SEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY CON­
NECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY, CON­
TRACT, TORT , OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY PER­
SONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED
FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR SER­
VICES PROVIDED HEREUNDER.''

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 (not up­to­date):
OPERATING SYSTEM COMPILER
Sun OS gcc and cc (3.0.1)
Sun Solaris gcc and cc
Silicon Graphics IRIX gcc and cc
Silicon Graphics IRIX64 MIPS
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/NT Borland C++ V4.5
Windows 95/98/NT/ME/XP Microsoft/Compaq Visual C++ v5.0, v6.0
Windows 95/98/NT Cygwin gcc
MacOS 7.1 or greater Metrowerks 10.+
MacOS­X 10.1 or greater cc (gcc)
CFITSIO will probably run on most other Unix platforms. Cray supercomputers are currently not
supported.
2.1.1 Unix Systems
The CFITSIO library is built on Unix systems by typing:
5

6 CHAPTER 2. CREATING THE CFITSIO LIBRARY
> ./configure [­­prefix=/target/installation/path] [­­enable­reentrant]
[­­enable­sse2] [­­enable­ssse3]
> make (or 'make shared')
> make install (this step is optional)
at the operating system prompt. The configure command customizes the Makefile for the particular
system, then the `make' command compiles the source files and builds the library. 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 optional 'prefix' argument to configure gives the
path to the directory where the CFITSIO library and include files should be installed via the later
'make install' command. For example,
> ./configure ­­prefix=/usr1/local
will cause the 'make install' command to copy the CFITSIO libcfitsio file to /usr1/local/lib and the
necessary include files to /usr1/local/include (assuming of course that the process has permission
to write to these directories).
The optional --enable­reentrant flag will attempt to configure CFITSIO so that it can be used
in multi­threaded programs. See the ''Using CFITSIO in Multi­threaded Environments'' section,
below, for more
The optional --enable­sse2 and --enable­ssse3 flags will cause configure to attempt to build CFITSIO
using faster byte­swapping algorithms. See the ''Optimizing Programs'' chapter of this manual for
more information about these options.
The 'make shared' option builds a shared or dynamic version of the CFITSIO library. 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 of using a shared library 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:
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 penalty, 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. BUILDING THE LIBRARY 7
On Mac OS X platforms the 'make shared' command works like on other UNIX platforms, but a
.dylib file will be created instead of .so. If installed in a nonstandard location, add its location to
the DYLD LIBRARY PATH environment variable so that the library can be found at run time.
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 statically 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.
2.1.2 VMS
On VAX/VMS and ALPHA/VMS systems the make gfloat.com command file may be executed 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 of the Borland or Microsoft
Visual C++ compilers in the files cfitsiodll 3xxx borland.zip and cfitsiodll 3xxx vcc.zip, where
'3xxx' represents the current release number. These zip archives also contains other files and
instructions on how to use the CFITSIO DLL library.
The CFITSIO library may also be built from the source code using the makefile.bc or makefile.vcc
files. Finally, the makepc.bat file gives an example of building CFITSIO with the Borland C++
v4.5 or v5.5 compiler using older DOS commands.
2.1.4 Macintosh PCs
When building on Mac OS­X, users should follow the Unix instructions, above. See the README.MacOS
file for instructions on building a Universal Binary that supports both Intel and PowerPC CPUs.

8 CHAPTER 2. CREATING THE CFITSIO LIBRARY
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 test 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 test­
prog.out. The 'di#' and 'cmp' commands shown above should not report any di#erences in the
files. (There may be some minor format di#erences, 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 tes