\contentsline {chapter}{\numberline {1}Introduction }{1} \contentsline {chapter}{\numberline {2} Creating the CFITSIO Library }{3} \contentsline {section}{\numberline {2.1}Building the Library}{3} \contentsline {subsection}{\numberline {2.1.1} Unix Systems}{4} \contentsline {subsection}{\numberline {2.1.2}VMS}{5} \contentsline {subsection}{\numberline {2.1.3}Windows PCs}{5} \contentsline {subsection}{\numberline {2.1.4}OS/2}{5} \contentsline {subsection}{\numberline {2.1.5}Macintosh PCs}{6} \contentsline {section}{\numberline {2.2}Testing the Library}{6} \contentsline {section}{\numberline {2.3}Linking Programs with CFITSIO}{7} \contentsline {section}{\numberline {2.4}Getting Started with CFITSIO}{7} \contentsline {section}{\numberline {2.5}Example Program}{8} \contentsline {section}{\numberline {2.6}Legal Stuff}{9} \contentsline {section}{\numberline {2.7}Acknowledgements}{10} \contentsline {chapter}{\numberline {3} A FITS Primer }{13} \contentsline {chapter}{\numberline {4} Extended File Name Syntax }{15} \contentsline {section}{\numberline {4.1}Overview}{15} \contentsline {section}{\numberline {4.2}Detailed Filename Syntax}{17} \contentsline {subsection}{\numberline {4.2.1}Filetype}{18} \contentsline {subsubsection}{Notes about the root filetype}{18} \contentsline {subsubsection}{Notes about the shmem filetype:}{20} \contentsline {subsection}{\numberline {4.2.2}Base Filename}{21} \contentsline {subsection}{\numberline {4.2.3}Output File Name when Opening an Existing File}{22} \contentsline {subsection}{\numberline {4.2.4}Template File Name when Creating a New File}{23} \contentsline {subsubsection}{Detailed Template Line Format}{23} \contentsline {subsubsection}{Auto-indexing of Keywords}{24} \contentsline {subsubsection}{Template Parser Directives}{25} \contentsline {subsubsection}{Formal Template Syntax}{26} \contentsline {subsubsection}{Errors}{26} \contentsline {subsubsection}{Examples}{26} \contentsline {subsection}{\numberline {4.2.5}HDU Location Specification}{27} \contentsline {subsection}{\numberline {4.2.6}Image Section}{28} \contentsline {subsection}{\numberline {4.2.7}Column and Keyword Filtering Specification}{29} \contentsline {subsection}{\numberline {4.2.8}Row Filtering Specification}{30} \contentsline {subsection}{\numberline {4.2.9}Binning or Histogramming Specification}{37} \contentsline {chapter}{\numberline {5}CFITSIO Conventions and Guidelines }{41} \contentsline {section}{\numberline {5.1}CFITSIO Definitions}{41} \contentsline {section}{\numberline {5.2}CFITSIO Size Limitations}{43} \contentsline {section}{\numberline {5.3}Multiple Access to the Same FITS File}{44} \contentsline {section}{\numberline {5.4}Current Header Data Unit (CHDU)}{44} \contentsline {section}{\numberline {5.5}Function Names and Datatypes}{44} \contentsline {section}{\numberline {5.6}Unsigned Integers}{46} \contentsline {section}{\numberline {5.7}Character Strings}{48} \contentsline {section}{\numberline {5.8}Implicit Data Type Conversion}{49} \contentsline {section}{\numberline {5.9}Data Scaling}{49} \contentsline {section}{\numberline {5.10}Error Status Values and the Error Message Stack}{50} \contentsline {section}{\numberline {5.11}Variable-Length Arrays in Binary Tables}{50} \contentsline {section}{\numberline {5.12}Support for IEEE Special Values}{52} \contentsline {section}{\numberline {5.13}When the Final Size of the FITS HDU is Unknown}{52} \contentsline {section}{\numberline {5.14}Local FITS Conventions supported by CFITSIO}{53} \contentsline {subsection}{\numberline {5.14.1}Long String Keyword Values.}{53} \contentsline {subsection}{\numberline {5.14.2}Arrays of Fixed-Length Strings in Binary Tables}{54} \contentsline {subsection}{\numberline {5.14.3}Keyword Units Strings}{54} \contentsline {subsection}{\numberline {5.14.4}HIERARCH Convention for Extended Keyword Names}{55} \contentsline {section}{\numberline {5.15}Optimizing Code for Maximum Processing Speed}{56} \contentsline {subsection}{\numberline {5.15.1}Background Information: How CFITSIO Manages Data I/O}{56} \contentsline {subsection}{\numberline {5.15.2}Optimization Strategies}{57} \contentsline {chapter}{\numberline {6} The CFITSIO Iterator Function }{61} \contentsline {section}{\numberline {6.1}The Iterator Work Function}{62} \contentsline {section}{\numberline {6.2}The Iterator Driver Function}{64} \contentsline {section}{\numberline {6.3}Guidelines for Using the Iterator Function}{65} \contentsline {chapter}{\numberline {7} Basic CFITSIO Interface Routines }{67} \contentsline {section}{\numberline {7.1}CFITSIO Error Status Routines}{67} \contentsline {section}{\numberline {7.2}FITS File Access Routines}{68} \contentsline {section}{\numberline {7.3}HDU Access Routines}{71} \contentsline {section}{\numberline {7.4}Header Keyword Read/Write Routines}{73} \contentsline {section}{\numberline {7.5}Iterator Routines}{76} \contentsline {section}{\numberline {7.6}Primary Array or IMAGE Extension I/O Routines}{78} \contentsline {section}{\numberline {7.7}ASCII and Binary Table Routines}{80} \contentsline {subsection}{\numberline {7.7.1}Column Information Routines }{80} \contentsline {subsection}{\numberline {7.7.2}Routines to Edit Rows or Columns }{82} \contentsline {subsection}{\numberline {7.7.3}Read and Write Column Data Routines }{83} \contentsline {section}{\numberline {7.8}Celestial Coordinate System Routines }{85} \contentsline {subsection}{\numberline {7.8.1} Self-contained WCS Routines}{86} \contentsline {subsection}{\numberline {7.8.2}WCS Routines that require the WCS library}{87} \contentsline {section}{\numberline {7.9}Hierarchical Grouping Convention Support Routines}{89} \contentsline {section}{\numberline {7.10}Row Selection and Calculator Routines}{94} \contentsline {section}{\numberline {7.11}File Checksum Routines }{95} \contentsline {section}{\numberline {7.12} Date and Time Utility Routines}{97} \contentsline {section}{\numberline {7.13} General Utility Routines}{98} \contentsline {chapter}{\numberline {8} Specialized CFITSIO Interface Routines }{105} \contentsline {section}{\numberline {8.1}Specialized FITS File Access Routines}{105} \contentsline {section}{\numberline {8.2}Specialized HDU Access Routines}{106} \contentsline {section}{\numberline {8.3}Specialized Header Keyword Routines}{108} \contentsline {subsection}{\numberline {8.3.1}Header Information Routines}{108} \contentsline {subsection}{\numberline {8.3.2}Read and Write the Required Keywords}{109} \contentsline {subsection}{\numberline {8.3.3}Specialized Write Keyword Routines}{110} \contentsline {subsection}{\numberline {8.3.4} Insert Keyword Routines}{113} \contentsline {subsection}{\numberline {8.3.5} Specialized Read Keyword Routines}{114} \contentsline {subsection}{\numberline {8.3.6} Modify Keyword Routines}{115} \contentsline {subsection}{\numberline {8.3.7} Specialized Update Keyword Routines }{116} \contentsline {section}{\numberline {8.4}Define Data Scaling and Undefined Pixel Parameters}{117} \contentsline {section}{\numberline {8.5}Specialized FITS Primary Array or IMAGE Extension I/O Routines}{118} \contentsline {section}{\numberline {8.6}Specialized FITS ASCII and Binary Table Routines}{123} \contentsline {subsection}{\numberline {8.6.1}Column Information Routines}{123} \contentsline {subsection}{\numberline {8.6.2}Low-Level Table Access Routines }{124} \contentsline {subsection}{\numberline {8.6.3}Specialized Write Column Data Routines}{124} \contentsline {subsection}{\numberline {8.6.4}Specialized Read Column Data Routines}{125} \contentsline {chapter}{\numberline {A}Index of Routines }{129} \contentsline {chapter}{\numberline {B}Parameter Definitions }{133} \contentsline {chapter}{\numberline {C}CFITSIO Error Status Codes }{139}