This chapter describes the main CFITSIO routines that can be used to perform the most common types of operations on FITS files.
void fits_report_error(FILE *stream, int status) void fits_get_errstatus(int status, char *err_text) float fits_get_version(float *version)
The first routine prints out information about any error that has occurred. Whenever any CFITSIO routine encounters an error it usually writes a message describing the nature of the error to an internal error message stack and then returns with a positive integer status value. Passing the error status value to this routine will cause a generic description of the error and all the messages from the internal CFITSIO error stack to be printed to the specified stream. The stream parameter is usually set equal to "stdout" or "stderr".
The second routine simply returns a 30-character descriptive error message corresponding to the input status value.
The last routine returns the current CFITSIO library version number.
int fits_open_file( fitsfile **fptr, char *filename, int mode, int *status) int fits_open_data( fitsfile **fptr, char *filename, int mode, int *status) int fits_open_table(fitsfile **fptr, char *filename, int mode, int *status) int fits_open_image(fitsfile **fptr, char *filename, int mode, int *status) int fits_create_file(fitsfile **fptr, char *filename, int *status) int fits_close_file(fitsfile *fptr, int *status)
These routines open or close a file. The first fitsfile parameter in these and nearly every other CFITSIO routine is a pointer to a structure that CFITSIO uses to store relevant parameters about each opened file. You should never directly read or write any information in this structure. Memory for this structure is allocated automatically when the file is opened or created, and is freed when the file is closed.
The mode parameter in the fits_open_xxxx set of routines can be set to either READONLY or READWRITE to select the type of file access that will be allowed. These symbolic constants are defined in fitsio.h.
The fits_open_file routine opens the file and positions the internal file pointer to the beginning of the file, or to the specified extension if an extension name or number is appended to the file name (see the later section on “CFITSIO File Names and Filters” for a description of the syntax). fits_open_data behaves similarly except that it will move to the first HDU containing significant data if a HDU name or number to open is not explicitly specified as part of the filename. It will move to the first IMAGE HDU with NAXIS greater than 0, or the first table that does not contain the strings ‘GTI’ (a Good Time Interval extension) or ‘OBSTABLE’ in the EXTNAME keyword value. The fits_open_table and fits_open_image routines are similar except that they will move to the first significant table HDU or image HDU, respectively if a HDU name of number is not specified as part of the input file name.
When opening an existing file, the filename can include optional arguments, enclosed in square brackets that specify filtering operations that should be applied to the input file. For example,
myfile.fit[EVENTS][counts > 0]
opens the table in the EVENTS extension and creates a virtual table by selecting only those rows where the COUNTS column value is greater than 0. See section 5 for more examples of these powerful filtering capabilities.
In fits_create_file, the filename is simply the root name of
the file to be created. You can overwrite an existing file by
prefixing the name with a ‘!’ character (on the Unix command line this
must be prefixed with a backslash, as in `\!file.fit').
If the file name ends with .gz the file will be compressed
using the gzip algorithm. If the
filename is stdout or "-" (a single dash character)
then the output file will be piped to the stdout stream. You can
chain several tasks together by writing the output from the first task
to stdout and then reading the input file in the 2nd task from
stdin or "-".
The routines listed in this section operate on Header-Data Units (HDUs) in a file.
_______________________________________________________________ int fits_get_num_hdus(fitsfile *fptr, int *hdunum, int *status) int fits_get_hdu_num(fitsfile *fptr, int *hdunum)
The first routines returns the total number of HDUs in the FITS file, and the second routine returns the position of the currently opened HDU in the FITS file (starting with 1, not 0).
__________________________________________________________________________
int fits_movabs_hdu(fitsfile *fptr, int hdunum, int *hdutype, int *status)
int fits_movrel_hdu(fitsfile *fptr, int nmove, int *hdutype, int *status)
int fits_movnam_hdu(fitsfile *fptr, int hdutype, char *extname,
int extver, int *status)
These routines enable you to move to a different HDU in the file. Most of the CFITSIO functions which read or write keywords or data operate only on the currently opened HDU in the file. The first routine moves to the specified absolute HDU number in the FITS file (the first HDU = 1), whereas the second routine moves a relative number of HDUs forward or backward from the currently open HDU. The hdutype parameter returns the type of the newly opened HDU, and will be equal to one of these symbolic constant values: IMAGE_HDU, ASCII_TBL, or BINARY_TBL. hdutype may be set to NULL if it is not needed. The third routine moves to the (first) HDU that matches the input extension type, name, and version number, as given by the XTENSION, EXTNAME (or HDUNAME) and EXTVER keywords. If the input value of extver = 0, then the version number will be ignored when looking for a matching HDU.
_________________________________________________________________ int fits_get_hdu_type(fitsfile *fptr, int *hdutype, int *status)
Get the type of the current HDU in the FITS file: IMAGE_HDU, ASCII_TBL, or BINARY_TBL.
____________________________________________________________________
int fits_copy_hdu(fitsfile *infptr, fitsfile *outfptr, int morekeys,
int *status)
int fits_copy_file(fitsfile *infptr, fitsfile *outfptr, int previous,
int current, int following, > int *status)
The first routine copies the current HDU from the FITS file associated with infptr and appends it to the end of the FITS file associated with outfptr. Space may be reserved for morekeys additional keywords in the output header. The second routine copies any HDUs previous to the current HDU, and/or the current HDU, and/or any HDUs following the current HDU, depending on the value (True or False) of previous, current, and following, respectively. For example,
fits_copy_file(infptr, outfptr, 0, 1, 1, &status);
will copy the current HDU and any HDUs that follow it from the input to the output file, but it will not copy any HDUs preceding the current HDU.
This section lists the more important CFITSIO routines which operate on FITS images.
_______________________________________________________________
int fits_get_img_type(fitsfile *fptr, int *bitpix, int *status)
int fits_get_img_dim( fitsfile *fptr, int *naxis, int *status)
int fits_get_img_size(fitsfile *fptr, int maxdim, long *naxes,
int *status)
int fits_get_img_param(fitsfile *fptr, int maxdim, int *bitpix,
int *naxis, long *naxes, int *status)
Get information about the currently opened image HDU. The first routine returns the datatype of the image as (defined by the BITPIX keyword), which can have the following symbolic constant values:
BYTE_IMG = 8 ( 8-bit byte pixels, 0 - 255)
SHORT_IMG = 16 (16 bit integer pixels)
LONG_IMG = 32 (32-bit integer pixels)
LONGLONG_IMG = 64 (64-bit integer pixels)
FLOAT_IMG = -32 (32-bit floating point pixels)
DOUBLE_IMG = -64 (64-bit floating point pixels)
The second and third routines return the number of dimensions in the image (from the NAXIS keyword), and the sizes of each dimension (from the NAXIS1, NAXIS2, etc. keywords). The last routine simply combines the function of the first 3 routines. The input maxdim parameter in this routine gives the maximum number dimensions that may be returned (i.e., the dimension of the naxes array)
__________________________________________________________
int fits_create_img(fitsfile *fptr, int bitpix, int naxis,
long *naxes, int *status)
Create an image HDU by writing the required keywords which define the structure of the image. The 2nd through 4th parameters specified the datatype, the number of dimensions, and the sizes of the dimensions. The allowed values of the bitpix parameter are listed above in the description of the fits_get_img_type routine. If the FITS file pointed to by fptr is empty (previously created with fits_create_file) then this routine creates a primary array in the file, otherwise a new IMAGE extension is appended to end of the file following the other HDUs in the file.
______________________________________________________________
int fits_write_pix(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *array, int *status);
int fits_write_pixnull(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *array, void *nulval, int *status);
int fits_read_pix(fitsfile *fptr, int datatype, long *fpixel,
long nelements, void *nulval, void *array,
int *anynul, int *status)
Read or write all or part of the FITS image. There are 2 different ’write’ pixel routines: The first simply writes the input array of pixels to the FITS file. The second is similar, except that it substitutes the appropriate null pixel value in the FITS file for any pixels which have a value equal to *nulval (note that this parameter gives the address of the null pixel value, not the value itself). Similarly, when reading an image, CFITSIO will substitute the value given by nulval for any undefined pixels in the image, unless nulval = NULL, in which case no checks will be made for undefined pixels when reading the FITS image.
The fpixel parameter in these routines is an array which gives the coordinate in each dimension of the first pixel to be read or written, and nelements is the total number of pixels to read or write. array is the address of an array which either contains the pixel values to be written, or will hold the values of the pixels that are read. When reading, array must have been allocated large enough to hold all the returned pixel values. These routines starts at the fpixel location and then read or write the nelements pixels, continuing on successive rows of the image if necessary. For example, to write an entire 2D image, set fpixel[0] = fpixel[1] = 1, and nelements = NAXIS1 * NAXIS2. Or to read just the 10th row of the image, set fpixel[0] = 1, fpixel[1] = 10, and nelements = NAXIS1. The datatype parameter specifies the datatype of the C array in the program, which need not be the same as the datatype of the FITS image itself. If the datatypes differ then CFITSIO will convert the data as it is read or written. The following symbolic constants are allowed for the value of datatype:
TBYTE unsigned char TSBYTE signed char TSHORT signed short TUSHORT unsigned short TINT signed int TUINT unsigned int TLONG signed long TLONGLONG signed 8-byte integer TULONG unsigned long TFLOAT float TDOUBLE double
_________________________________________________________________
int fits_write_subset(fitsfile *fptr, int datatype, long *fpixel,
long *lpixel, DTYPE *array, > int *status)
int fits_read_subset(fitsfile *fptr, int datatype, long *fpixel,
long *lpixel, long *inc, void *nulval, void *array,
int *anynul, int *status)
Read or write a rectangular section of the FITS image. These are very similar to fits_write_pix and fits_read_pix except that you specify the last pixel coordinate (the upper right corner of the section) instead of the number of pixels to be read. The read routine also has an inc parameter which can be used to read only every inc-th pixel along each dimension of the image. Normally inc[0] = inc[1] = 1 to read every pixel in a 2D image. To read every other pixel in the entire 2D image, set
fpixel[0] = fpixel[1] = 1
lpixel[0] = {NAXIS1}
lpixel[1] = {NAXIS2}
inc[0] = inc[1] = 2
Or, to read the 8th row of a 2D image, set
fpixel[0] = 1
fpixel[1] = 8
lpixel[0] = {NAXIS1}
lpixel[1] = 8
inc[0] = inc[1] = 1
This section lists the most important CFITSIO routines which operate on FITS tables.
__________________________________________________________________________
int fits_create_tbl(fitsfile *fptr, int tbltype, long nrows, int tfields,
char *ttype[],char *tform[], char *tunit[], char *extname, int *status)
Create a new table extension by writing the required keywords that define the table structure. The required null primary array will be created first if the file is initially completely empty. tbltype defines the type of table and can have values of ASCII_TBL or BINARY_TBL. Binary tables are generally preferred because they are more efficient and support a greater range of column datatypes than ASCII tables.
The nrows parameter gives the initial number of empty rows to be allocated for the table; this should normally be set to 0. The tfields parameter gives the number of columns in the table (maximum = 999). The ttype, tform, and tunit parameters give the name, datatype, and physical units of each column, and extname gives the name for the table (the value of the EXTNAME keyword). The FITS Standard recommends that only letters, digits, and the underscore character be used in column names with no embedded spaces. It is recommended that all the column names in a given table be unique within the first 8 characters.
The following table shows the TFORM column format values that are allowed in ASCII tables and in binary tables:
ASCII Table Column Format Codes
-------------------------------
(w = column width, d = no. of decimal places to display)
Aw - character string
Iw - integer
Fw.d - fixed floating point
Ew.d - exponential floating point
Dw.d - exponential floating point
Binary Table Column Format Codes
--------------------------------
(r = vector length, default = 1)
rA - character string
rAw - array of strings, each of length w
rL - logical
rX - bit
rB - unsigned byte
rS - signed byte **
rI - signed 16-bit integer
rU - unsigned 16-bit integer **
rJ - signed 32-bit integer
rV - unsigned 32-bit integer **
rK - signed 64-bit integer
rE - 32-bit floating point
rD - 64-bit floating point
rC - 32-bit complex pair
rM - 64-bit complex pair
** The S, U and V format codes are not actual legal TFORMn values.
CFITSIO substitutes the somewhat more complicated set of
keywords that are used to represent unsigned integers or
signed bytes.
The tunit and extname parameters are optional and may be set to NULL if they are not needed.
Note that it may be easier to create a new table by copying the header from another existing table with fits_copy_header rather than calling this routine.
_______________________________________________________________ int fits_get_num_rows(fitsfile *fptr, long *nrows, int *status) int fits_get_num_cols(fitsfile *fptr, int *ncols, int *status)
Get the number of rows or columns in the current FITS table. The number of rows is given by the NAXIS2 keyword and the number of columns is given by the TFIELDS keyword in the header of the table.
_______________________________________________________________
int fits_get_colnum(fitsfile *fptr, int casesen, char *template,
int *colnum, int *status)
int fits_get_colname(fitsfile *fptr, int casesen, char *template,
char *colname, int *colnum, int *status)
Get the column number (starting with 1, not 0) of the column whose name matches the specified template name. The only difference in these 2 routines is that the 2nd one also returns the name of the column that matched the template string.
Normally, casesen should be set to CASEINSEN, but it may be set to CASESEN to force the name matching to be case-sensitive.
The input template string gives the name of the desired column and may include wildcard characters: a ‘*’ matches any sequence of characters (including zero characters), ‘?’ matches any single character, and ‘#’ matches any consecutive string of decimal digits (0-9). If more than one column name in the table matches the template string, then the first match is returned and the status value will be set to COL_NOT_UNIQUE as a warning that a unique match was not found. To find the next column that matches the template, call this routine again leaving the input status value equal to COL_NOT_UNIQUE. Repeat this process until status = COL_NOT_FOUND is returned.
_______________________________________________________________
int fits_get_coltype(fitsfile *fptr, int colnum, int *typecode,
long *repeat, long *width, int *status)
int fits_get_eqcoltype(fitsfile *fptr, int colnum, int *typecode,
long *repeat, long *width, int *status)
Return the datatype, vector repeat count, and the width in bytes of a single column element for column number colnum. Allowed values for the returned datatype in ASCII tables are: TSTRING, TSHORT, TLONG, TFLOAT, and TDOUBLE. Binary tables support these additional types: TLOGICAL, TBIT, TBYTE, TINT32BIT, TCOMPLEX and TDBLCOMPLEX. The negative of the datatype code value is returned if it is a variable length array column.
These 2 routines are similar, except that in the case of scaled integer columns the 2nd routine, fit_get_eqcoltype, returns the ’equivalent’ datatype that is needed to store the scaled values, which is not necessarily the same as the physical datatype of the unscaled values as stored in the FITS table. For example if a ’1I’ column in a binary table has TSCALn = 1 and TZEROn = 32768, then this column effectively contains unsigned short integer values, and thus the returned value of typecode will be TUSHORT, not TSHORT. Or, if TSCALn or TZEROn are not integers, then the equivalent datatype will be returned as TFLOAT or TDOUBLE, depending on the size of the integer.
The repeat count is always 1 in ASCII tables. The ’repeat’ parameter returns the vector repeat count on the binary table TFORMn keyword value. (ASCII table columns always have repeat = 1). The ’width’ parameter returns the width in bytes of a single column element (e.g., a ’10D’ binary table column will have width = 8, an ASCII table ’F12.2’ column will have width = 12, and a binary table’60A’ character string column will have width = 60); Note that this routine supports the local convention for specifying arrays of fixed length strings within a binary table character column using the syntax TFORM = ’rAw’ where ’r’ is the total number of characters (= the width of the column) and ’w’ is the width of a unit string within the column. Thus if the column has TFORM = ’60A12’ then this means that each row of the table contains 5 12-character substrings within the 60-character field, and thus in this case this routine will return typecode = TSTRING, repeat = 60, and width = 12. The number of substings in any binary table character string field can be calculated by (repeat/width). A null pointer may be given for any of the output parameters that are not needed.
____________________________________________________________________________ int fits_insert_rows(fitsfile *fptr, long firstrow, long nrows, int *status) int fits_delete_rows(fitsfile *fptr, long firstrow, long nrows, int *status) int fits_delete_rowrange(fitsfile *fptr, char *rangelist, int *status) int fits_delete_rowlist(fitsfile *fptr, long *rowlist, long nrows, int *stat)
Insert or delete rows in a table. The blank rows are inserted immediately following row frow. Set frow = 0 to insert rows at the beginning of the table. The first ’delete’ routine deletes nrows rows beginning with row firstrow. The 2nd delete routine takes an input string listing the rows or row ranges to be deleted (e.g., ’2,4-7, 9-12’). The last delete routine takes an input long integer array that specifies each individual row to be deleted. The row lists must be sorted in ascending order. All these routines update the value of the NAXIS2 keyword to reflect the new number of rows in the table.
_________________________________________________________________________
int fits_insert_col(fitsfile *fptr, int colnum, char *ttype, char *tform,
int *status)
int fits_insert_cols(fitsfile *fptr, int colnum, int ncols, char **ttype,
char **tform, int *status)
int fits_delete_col(fitsfile *fptr, int colnum, int *status)
Insert or delete columns in a table. colnum gives the position of the column to be inserted or deleted (where the first column of the table is at position 1). ttype and tform give the column name and column format, where the allowed format codes are listed above in the description of the fits_create_table routine. The 2nd ’insert’ routine inserts multiple columns, where ncols is the number of columns to insert, and ttype and tform are arrays of string pointers in this case.
____________________________________________________________________
int fits_copy_col(fitsfile *infptr, fitsfile *outfptr, int incolnum,
int outcolnum, int create_col, int *status);
Copy a column from one table HDU to another. If create_col = TRUE (i.e., not equal to zero), then a new column will be inserted in the output table at position outcolumn, otherwise the values in the existing output column will be overwritten.
__________________________________________________________________________
int fits_write_col(fitsfile *fptr, int datatype, int colnum, long firstrow,
long firstelem, long nelements, void *array, int *status)
int fits_write_colnull(fitsfile *fptr, int datatype, int colnum,
long firstrow, long firstelem, long nelements,
void *array, void *nulval, int *status)
int fits_write_col_null(fitsfile *fptr, int colnum, long firstrow,
long firstelem, long nelements, int *status)
int fits_read_col(fitsfile *fptr, int datatype, int colnum, long firstrow,
long firstelem, long nelements, void *nulval, void *array,
int *anynul, int *status)
Write or read elements in column number colnum, starting with row firstsrow and element firstelem (if it is a vector column). firstelem is ignored if it is a scalar column. The nelements number of elements are read or written continuing on successive rows of the table if necessary. array is the address of an array which either contains the values to be written, or will hold the returned values that are read. When reading, array must have been allocated large enough to hold all the returned values.
There are 3 different ’write’ column routines: The first simply writes the input array into the column. The second is similar, except that it substitutes the appropriate null pixel value in the column for any input array values which are equal to *nulval (note that this parameter gives the address of the null pixel value, not the value itself). The third write routine sets the specified table elements to a null value. New rows will be automatical added to the table if the write operation extends beyond the current size of the table.
When reading a column, CFITSIO will substitute the value given by nulval for any undefined elements in the FITS column, unless nulval or *nulval = NULL, in which case no checks will be made for undefined values when reading the column.
datatype specifies the datatype of the C array in the program, which need not be the same as the intrinsic datatype of the column in the FITS table. The following symbolic constants are allowed for the value of datatype:
TSTRING array of character string pointers TBYTE unsigned char TSHORT signed short TUSHORT unsigned short TINT signed int TUINT unsigned int TLONG signed long TLONGLONG signed 8-byte integer TULONG unsigned long TFLOAT float TDOUBLE double
Note that TSTRING corresponds to the C char** datatype, i.e., a pointer to an array of pointers to an array of characters.
Any column, regardless of it’s intrinsic datatype, may be read as a TSTRING character string. The display format of the returned strings will be determined by the TDISPn keyword, if it exists, otherwise a default format will be used depending on the datatype of the column. The tablist example utility program (available from the CFITSIO web site) uses this feature to display all the values in a FITS table.
_____________________________________________________________________
int fits_select_rows(fitsfile *infptr, fitsfile *outfptr, char *expr,
int *status)
int fits_calculator(fitsfile *infptr, char *expr, fitsfile *outfptr,
char *colname, char *tform, int *status)
These are 2 of the most powerful routines in the CFITSIO library. (See the full CFITSIO Reference Guide for a description of several related routines). These routines can perform complicated transformations on tables based on an input arithmetic expression which is evaluated for each row of the table. The first routine will select or copy rows of the table for which the expression evaluates to TRUE (i.e., not equal to zero). The second routine writes the value of the expression to a column in the output table. Rather than supplying the expression directly to these routines, the expression may also be written to a text file (continued over multiple lines if necessary) and the name of the file, prepended with a ’@’ character, may be supplied as the value of the ’expr’ parameter (e.g. ’@filename.txt’).
The arithmetic expression may be a function of any column or keyword in the input table as shown in these examples:
Row Selection Expressions:
counts > 0 uses COUNTS column value
sqrt( X**2 + Y**2) < 10. uses X and Y column values
(X > 10) || (X < -10) && (Y == 0) used 'or' and 'and' operators
gtifilter() filter on Good Time Intervals
regfilter("myregion.reg") filter using a region file
@select.txt reads expression from a text file
Calculator Expressions:
#row % 10 modulus of the row number
counts/#exposure Fn of COUNTS column and EXPOSURE keyword
dec < 85 ? cos(dec * #deg) : 0 Conditional expression: evaluates to
cos(dec) if dec < 85, else 0
(count{-1}+count+count{+1})/3. running mean of the count values in the
previous, current, and next rows
max(0, min(X, 1000)) returns a value between 0 - 1000
@calc.txt reads expression from a text file
Most standard mathematical operators and functions are supported. If the expression includes the name of a column, than the value in the current row of the table will be used when evaluating the expression on each row. An offset to an adjacent row can be specified by including the offset value in curly brackets after the column name as shown in one of the examples. Keyword values can be included in the expression by preceding the keyword name with a ‘#’ sign. See Section 5 of this document for more discussion of the expression syntax.
gtifilter is a special function which tests whether the TIME column value in the input table falls within one or more Good Time Intervals. By default, this function looks for a ’GTI’ extension in the same file as the input table. The ’GTI’ table contains START and STOP columns which define the range of each good time interval. See section 5.4.3 for more details.
regfilter is another special function which selects rows based on whether the spatial position associated with each row is located within in a specified region of the sky. By default, the X and Y columns in the input table are assumed to give the position of each row. The spatial region is defined in an ASCII text file whose name is given as the argument to the regfilter function. See section 5.4.4 for more details.
The infptr and outfptr parameters in these routines may point to the same table or to different tables. In fits_select_rows, if the input and output tables are the same then the rows that do not satisfy the selection expression will be deleted from the table. Otherwise, if the output table is different from the input table then the selected rows will be copied from the input table to the output table.
The output column in fits_calculator may or may not already exist. If it exists then the calculated values will be written to that column, overwriting the existing values. If the column doesn’t exist then the new column will be appended to the output table. The tform parameter can be used to specify the datatype of the new column (e.g., the TFORM keyword value as in ’1E’, or ’1J’). If tform = NULL then a default datatype will be used, depending on the expression.
_____________________________________________________________________
int fits_read_tblbytes(fitsfile *fptr, long firstrow, long firstchar,
long nchars, unsigned char *array, int *status)
int fits_write_tblbytes (fitsfile *fptr, long firstrow, long firstchar,
long nchars, unsigned char *array, int *status)
These 2 routines provide low-level access to tables and are mainly useful as an efficient way to copy rows of a table from one file to another. These routines simply read or write the specified number of consecutive characters (bytes) in a table, without regard for column boundaries. For example, to read or write the first row of a table, set firstrow = 1, firstchar = 1, and nchars = NAXIS1 where the length of a row is given by the value of the NAXIS1 header keyword. When reading a table, array must have been declared at least nchars bytes long to hold the returned string of bytes.
The following routines read and write header keywords in the current HDU.
____________________________________________________________________
int fits_get_hdrspace(fitsfile *fptr, int *keysexist, int *morekeys,
int *status)
Return the number of existing keywords (not counting the mandatory END keyword) and the amount of empty space currently available for more keywords. The morekeys parameter may be set to NULL if it’s value is not needed.
___________________________________________________________________________
int fits_read_record(fitsfile *fptr, int keynum, char *record, int *status)
int fits_read_card(fitsfile *fptr, char *keyname, char *record, int *status)
int fits_read_key(fitsfile *fptr, int datatype, char *keyname,
void *value, char *comment, int *status)
int fits_find_nextkey(fitsfile *fptr, char **inclist, int ninc,
char **exclist, int nexc, char *card, int *status)
int fits_read_key_unit(fitsfile *fptr, char *keyname, char *unit,
int *status)
These routines all read a header record in the current HDU. The first routine reads keyword number keynum (where the first keyword is at position 1). This routine is most commonly used when sequentially reading every record in the header from beginning to end. The 2nd and 3rd routines read the named keyword and return either the whole record, or the keyword value and comment string. In each case any non-significant trailing blank characters in the strings are truncated.
Wild card characters (*, ?, and #) may be used when specifying the name of the keyword to be read, in which case the first matching keyword is returned.
The datatype parameter specifies the C datatype of the returned keyword value and can have one of the following symbolic constant values: TSTRING, TLOGICAL (== int), TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TFLOAT, TDOUBLE, TCOMPLEX, and TDBLCOMPLEX. Data type conversion will be performed for numeric values if the intrinsic FITS keyword value does not have the same datatype. The comment parameter may be set equal to NULL if the comment string is not needed.
The 4th routine provides an easy way to find all the keywords in the header that match one of the name templates in inclist and do not match any of the name templates in exclist. ninc and nexc are the number of template strings in inclist and exclist, respectively. Wild cards (*, ?, and #) may be used in the templates to match multiple keywords. Each time this routine is called it returns the next matching 80-byte keyword record. It returns status = KEY_NO_EXIST if there are no more matches.
The 5th routine returns the keyword value units string, if any. The units are recorded at the beginning of the keyword comment field enclosed in square brackets.
_______________________________________________________________
int fits_write_key(fitsfile *fptr, int datatype, char *keyname,
void *value, char *comment, int *status)
int fits_update_key(fitsfile *fptr, int datatype, char *keyname,
void *value, char *comment, int *status)
int fits_write_record(fitsfile *fptr, char *card, int *status)
int fits_modify_comment(fitsfile *fptr, char *keyname, char *comment,
int *status)
int fits_write_key_unit(fitsfile *fptr, char *keyname, char *unit,
int *status)
Write or modify a keyword in the header of the current HDU. The first routine appends the new keyword to the end of the header, whereas the second routine will update the value and comment fields of the keyword if it already exists, otherwise it behaves like the first routine and appends the new keyword. Note that value gives the address to the value and not the value itself. The datatype parameter specifies the C datatype of the keyword value and may have any of the values listed in the description of the keyword reading routines, above. A NULL may be entered for the comment parameter, in which case the keyword comment field will be unmodified or left blank.
The third routine is more primitive and simply writes the 80-character card record to the header. It is the programmer’s responsibility in this case to ensure that the record conforms to all the FITS format requirements for a header record.
The fourth routine modifies the comment string in an existing keyword, and the last routine writes or updates the keyword units string for an existing keyword. (The units are recorded at the beginning of the keyword comment field enclosed in square brackets).
___________________________________________________________________ int fits_write_comment(fitsfile *fptr, char *comment, int *status) int fits_write_history(fitsfile *fptr, char *history, int *status) int fits_write_date(fitsfile *fptr, int *status)
Write a COMMENT, HISTORY, or DATE keyword to the current header. The COMMENT keyword is typically used to write a comment about the file or the data. The HISTORY keyword is typically used to provide information about the history of the processing procedures that have been applied to the data. The comment or history string will be continued over multiple keywords if it is more than 70 characters long.
The DATE keyword is used to record the date and time that the FITS file was created. Note that this file creation date is usually different from the date of the observation which obtained the data in the FITS file. The DATE keyword value is a character string in ’yyyy-mm-ddThh:mm:ss’ format. If a DATE keyword already exists in the header, then this routine will update the value with the current system date.
___________________________________________________________________ int fits_delete_record(fitsfile *fptr, int keynum, int *status) int fits_delete_key(fitsfile *fptr, char *keyname, int *status)
Delete a keyword record. The first routine deletes a keyword at a specified position (the first keyword is at position 1, not 0), whereas the second routine deletes the named keyword.
_______________________________________________________________________ int fits_copy_header(fitsfile *infptr, fitsfile *outfptr, int *status)
Copy all the header keywords from the current HDU associated with infptr to the current HDU associated with outfptr. If the current output HDU is not empty, then a new HDU will be appended to the output file. The output HDU will then have the identical structure as the input HDU, but will contain no data.
This section lists the most important CFITSIO general utility routines.
___________________________________________________________________ int fits_write_chksum( fitsfile *fptr, int *status) int fits_verify_chksum(fitsfile *fptr, int *dataok, int *hduok, int *status)
These routines compute or validate the checksums for the currenrt HDU. The DATASUM keyword is used to store the numerical value of the 32-bit, 1’s complement checksum for the data unit alone. The CHECKSUM keyword is used to store the ASCII encoded COMPLEMENT of the checksum for the entire HDU. Storing the complement, rather than the actual checksum, forces the checksum for the whole HDU to equal zero. If the file has been modified since the checksums were computed, then the HDU checksum will usually not equal zero.
The returned dataok and hduok parameters will have a value = 1 if the data or HDU is verified correctly, a value = 0 if the DATASUM or CHECKSUM keyword is not present, or value = -1 if the computed checksum is not correct.
___________________________________________________________________ int fits_parse_value(char *card, char *value, char *comment, int *status) int fits_get_keytype(char *value, char *dtype, int *status) int fits_get_keyclass(char *card) int fits_parse_template(char *template, char *card, int *keytype, int *status)
fits_parse_value parses the input 80-chararacter header keyword record, returning the value (as a literal character string) and comment strings. If the keyword has no value (columns 9-10 not equal to ’= ’), then a null value string is returned and the comment string is set equal to column 9 - 80 of the input string.
fits_get_keytype parses the keyword value string to determine its datatype. dtype returns with a value of ’C’, ’L’, ’I’, ’F’ or ’X’, for character string, logical, integer, floating point, or complex, respectively.
fits_get_keyclass returns a classification code that indicates the classification type of the input keyword record (e.g., a required structural keyword, a TDIM keyword, a WCS keyword, a comment keyword, etc. See the CFITSIO Reference Guide for a list of the different classification codes.
fits_parse_template takes an input free format keyword template string and returns a formatted 80*char record that satisfies all the FITS requirements for a header keyword record. The template should generally contain 3 tokens: the keyword name, the keyword value, and the keyword comment string. The returned keytype parameter indicates whether the keyword is a COMMENT keyword or not. See the CFITSIO Reference Guide for more details.