next up previous contents
Next: 7. Including and Linking Up: CFHT FITS Handling Library Previous: 5. Setting Keyword Values   Contents

6. Summary of All Functions

NOTE: In this table, hu is a type HeaderUnit that was returned from a previous call to fh_create() or fh_ehu(), fd is an open file descriptor (type int) returned by a previous call to open(), and idx is a double floating point sorting number used internally by the library. Finally, where-ever name and comment are found, these are ASCII character strings (type char*). The must contain only those characters by the FITS standard.


Table 1: Functions to Open, Lock, Close, or create new FITS files
Return Function Parameters Description
HeaderUnit fh_file (const* filespec, fh_mode) Open and read header from a file or extension.
int fh_file_desc (HeaderUnit hu) Get the file descriptor used by fh_file
HeaderUnit fh_create No parameters Allocate a table to store FITS cards.
fh_result fh_destroy (HeaderUnit hu) Free memory associated with HeaderUnit. Check return!
fh_result fh_read (hu, int fd, double idx) Read header from an open file descriptor.
fh_result fh_reserve (hu, int n) Reserve at least n cards slots for downstream use.
fh_result fh_validate (hu) Test if HeaderUnit is complete and valid.
fh_result fh_write (hu, fd) Write header, padding, and END to an open file.
fh_result fh_write_padding (hu, fd) Write padding to go after the IMAGE.
fh_result fh_write_padded_image (hu, fd, void* data, size) Write image from `data' plus padding.
fh_result fh_read_padded_image (hu, fd, void* data, size) Read image in user allocated `data'.
fh_result fh_copy_padded_image (hu, fd_out, fd_in) Copy image and padding from another open file.
fh_result fh_rewrite (hu) Write the header back to the original file, if possible.


Table 2: Functions for looking at Extensions and Image data
Return Function Parameters Description
HeaderUnit fh_ehu (hu, int number) Seek to extension by its offset in the file (caution!)
HeaderUnit fh_ehu_by_imageid (hu, int imageid) Seek to extension with matching IMAGEID keyword.
HeaderUnit fh_ehu_by_extname (hu, char* extname) Seek by EXTNAME (e.g. ``im07'' or ``chip03b'')
int fh_extensions (hu) Reads NEXTEND to determine number of extensions.
int fh_image_bytes (hu) Reads BITPIX and NAXIS* to find (unpadded) image size.
int fh_image_blocks (hu) Converts fh_image_bytes to size in 2880-byte blocks.
int fh_header_blocks (hu) Returns size required for header, in 2880-byte blocks.


Table 3: Functions for Getting Keyword Values
Return Function Parameters Description
fh_result fh_get_bool (hu, char* name, int* value) *value gets 0 if F(alse) or 1 if T(rue)
fh_result fh_get_int (hu, char* name, int* value) *value gets integer value of `name'
fh_result fh_get_flt (hu, char* name, double* value) *value gets double-float value of `name'
fh_result fh_get_str (hu, char* name, char* value, maxlen) *value gets string value of `name'
double fh_idx_after (hu, char* name) Returns an `idx' that would cause a new header to be inserted after `name'
double fh_idx_before (hu, char* name) Returns an `idx' that would cause a new header to be inserted before `name'
fh_result fh_search (hu, char* name, double* idx) If FH_SUCCESS if found; if `idx' not NULL, it will return the card's `idx' value
fh_result fh_show (target_hu) Display a list on stdout (for debugging).


Table 4: Functions for Setting Keyword Values
Return Function Parameters Description
fh_result fh_remove (hu, char* name) Removes a card from the header unit in memory. It will disappear from the file on the next fh_rewrite()
fh_result fh_this_unit_only (hu) Overrides default behavior of fh_set*() functions, which normally change extensions too (if any).
fh_result fh_set_com (hu, idx, char* name, char* comment) Creates new command card containing up to 72 ASCII characters. ``name'' should be ``HISTORY'' or ``COMMENT''.
fh_result fh_set_bool (hu, idx,name, int value, comment) Changes or creates the card ``name'' and with new value of 'T' if value is non-zero, and sets comment field if comment is not empty.
fh_result fh_set_int (hu, idx, name, int value, comment) Changes or creates the card ``name'' and with new integer value and comment fields.
fh_result fh_set_flt (hu, idx, name, double value, comment) Changes or creates the card ``name'' and with new floating-point value and comment fields.
fh_result fh_set_str (hu, idx, name, char* value, comment) Changes or creates the card ``name'' and with new string value and comment fields.
fh_result fh_set_value (hu, idx, name, char* value, comment) Changes or creates the card ``name'' and with new pre-formatted value and comment fields. (Use typed functions above instead.)
fh_result fh_merge (target_hu, source_hu) Merges all cards from one list in another. Final order will depend on the sorting numbers contained in both.


next up previous contents
Next: 7. Including and Linking Up: CFHT FITS Handling Library Previous: 5. Setting Keyword Values   Contents
Sidik Isani
2001-04-22