FITSIO Home
Next:
Contents
CFITSIO User's Reference Guide
An Interface to FITS Format Files
for C Programmers
Version 4.3
HEASARC
Code 662
Goddard Space Flight Center
Greenbelt, MD 20771
USA
Jul 2023
Contents
1
. Introduction
1
.
1
A Brief Overview
1
.
2
Sources of FITS Software and Information
1
.
3
Acknowledgments
1
.
4
Legal Stuff
2
. Creating the CFITSIO Library
2
.
1
Building the Library
2
.
1
.
1
Unix Systems
2
.
1
.
2
VMS
2
.
1
.
3
Windows PCs
2
.
1
.
4
Macintosh PCs
2
.
2
Testing the Library
2
.
3
Linking Programs with CFITSIO
2
.
4
Using CFITSIO in Multi-threaded Environments
2
.
5
Getting Started with CFITSIO
2
.
6
Example Program
3
. A FITS Primer
4
. Programming Guidelines
4
.
1
CFITSIO Definitions
4
.
2
Current Header Data Unit (CHDU)
4
.
3
Function Names and Variable Datatypes
4
.
4
Support for Unsigned Integers and Signed Bytes
4
.
5
Dealing with Character Strings
4
.
6
Implicit Data Type Conversion
4
.
7
Data Scaling
4
.
8
Support for IEEE Special Values
4
.
9
Error Status Values and the Error Message Stack
4
.
10
Variable-Length Arrays in Binary Tables
4
.
11
Multiple Access to the Same FITS File
4
.
12
When the Final Size of the FITS HDU is Unknown
4
.
13
CFITSIO Size Limitations
5
. Basic CFITSIO Interface Routines
5
.
1
CFITSIO Error Status Routines
5
.
2
FITS File Access Routines
5
.
3
HDU Access Routines
5
.
4
Header Keyword Read/Write Routines
5
.
4
.
1
Keyword Reading Routines
5
.
4
.
2
Keyword Writing Routines
5
.
5
Primary Array or IMAGE Extension I/O Routines
5
.
6
Image Compression
5
.
7
ASCII and Binary Table Routines
5
.
7
.
1
Create New Table
5
.
7
.
2
Column Information Routines
5
.
7
.
3
Routines to Edit Rows or Columns
5
.
7
.
4
Read and Write Column Data Routines
5
.
7
.
5
Row Selection and Calculator Routines
5
.
7
.
6
Column Binning or Histogramming Routines
5
.
8
Utility Routines
5
.
8
.
1
File Checksum Routines
5
.
8
.
2
Date and Time Utility Routines
5
.
8
.
3
General Utility Routines
6
. The CFITSIO Iterator Function
6
.
1
The Iterator Work Function
6
.
2
The Iterator Driver Function
6
.
3
Guidelines for Using the Iterator Function
6
.
4
Complete List of Iterator Routines
7
. World Coordinate System Routines
7
.
1
Self-contained WCS Routines
8
. Hierarchical Grouping Routines
8
.
1
Grouping Table Routines
8
.
2
Group Member Routines
9
. Specialized CFITSIO Interface Routines
9
.
1
FITS File Access Routines
9
.
1
.
1
File Access
9
.
1
.
2
Download Utility Functions
9
.
2
HDU Access Routines
9
.
3
Specialized Header Keyword Routines
9
.
3
.
1
Header Information Routines
9
.
3
.
2
Read and Write the Required Keywords
9
.
3
.
3
Write Keyword Routines
9
.
3
.
4
Insert Keyword Routines
9
.
3
.
5
Read Keyword Routines
9
.
3
.
6
Modify Keyword Routines
9
.
3
.
7
Update Keyword Routines
9
.
4
Define Data Scaling and Undefined Pixel Parameters
9
.
5
Specialized FITS Primary Array or IMAGE Extension I/O Routines
9
.
6
Specialized FITS ASCII and Binary Table Routines
9
.
6
.
1
General Column Routines
9
.
6
.
2
Low-Level Table Access Routines
9
.
6
.
3
Write Column Data Routines
9
.
6
.
4
Read Column Data Routines
10
. Extended File Name Syntax
10
.
1
Overview
10
.
2
Filetype
10
.
2
.
1
Notes about HTTP proxy servers
10
.
2
.
2
Notes about HTTPS and FTPS file access
10
.
2
.
3
Notes about the stream filetype driver
10
.
2
.
4
Notes about the gsiftp filetype
10
.
2
.
5
Notes about the root filetype
10
.
2
.
6
Notes about the shmem filetype:
10
.
3
Base Filename
10
.
4
Output File Name when Opening an Existing File
10
.
5
Template File Name when Creating a New File
10
.
6
Image Tile-Compression Specification
10
.
7
HDU Location Specification
10
.
8
Image Section
10
.
9
Image Transform Filters
10
.
10
Column and Keyword Filtering Specification
10
.
11
Row Filtering Specification
10
.
11
.
1
General Syntax
10
.
11
.
2
Bit Masks
10
.
11
.
3
Vector Columns
10
.
11
.
4
Row Access
10
.
11
.
5
Good Time Interval Filtering and Calculation
10
.
11
.
6
Spatial Region Filtering
10
.
11
.
7
Example Row Filters
10
.
12
Binning or Histogramming Specification
11
. Template Files
11
.
1
Detailed Template Line Format
11
.
2
Auto-indexing of Keywords
11
.
3
Template Parser Directives
11
.
4
Formal Template Syntax
11
.
5
Errors
11
.
6
Examples
12
. Local FITS Conventions
12
.
1
64-Bit Long Integers
12
.
2
Long String Keyword Values.
12
.
3
Arrays of Fixed-Length Strings in Binary Tables
12
.
4
Keyword Units Strings
12
.
5
HIERARCH Convention for Extended Keyword Names
12
.
6
Tile-Compressed Image Format
13
. Optimizing Programs
13
.
1
How CFITSIO Manages Data I/O
13
.
2
Optimization Strategies
A. Index of Routines
B. Parameter Definitions
C. CFITSIO Error Status Codes
About this document ...
FITSIO Home