C Standard Library Extensions: FITS header handling

C Standard Library Extensions 6.2.0

- Main Page
- Modules
- Classes
- Files

Functions
FITS header handling

## Functions
qfits_header * | qfits_header_new (void)
| FITS header constructor.
qfits_header * | qfits_header_default (void)
| FITS header default constructor.
void | qfits_header_add (qfits_header *hdr, const char *key, const char *val, const char *com, const char *lin)
| Add a new card to a FITS header.
void | qfits_header_add_after (qfits_header *hdr, const char *after, const char *key, const char *val, const char *com, const char *lin)
| add a new card to a FITS header
void | qfits_header_append (qfits_header *hdr, const char *key, const char *val, const char *com, const char *lin)
| Append a new card to a FITS header.
void | qfits_header_del (qfits_header *hdr, const char *key)
| Delete a card in a FITS header.
void | qfits_header_mod (qfits_header *hdr, const char *key, const char *val, const char *com)
| Modifies a FITS card.
int | qfits_header_sort (qfits_header **hdr)
| Sort a FITS header.
qfits_header * | qfits_header_copy (const qfits_header *src)
| Copy a FITS header.
void | qfits_header_destroy (qfits_header *hdr)
| qfits_header destructor
char * | qfits_header_getstr (const qfits_header *hdr, const char *key)
| Return the value associated to a key, as a string.
int | qfits_header_getitem (const qfits_header *hdr, int idx, char *key, char *val, char *com, char *lin)
| Return the i-th key/val/com/line tuple in a header.
char * | qfits_header_getcom (const qfits_header *hdr, const char *key)
| Return the comment associated to a key, as a string.
int | qfits_header_getint (const qfits_header *hdr, const char *key, int errval)
| Return the value associated to a key, as an int.
double | qfits_header_getdouble (const qfits_header *hdr, const char *key, double errval)
| Return the value associated to a key, as a double.
int | qfits_header_getboolean (const qfits_header *hdr, const char *key, int errval)
| Return the value associated to a key, as a boolean (int).
int | qfits_header_dump (const qfits_header *hdr, FILE *out)
| Dump a FITS header to an opened file.

## Detailed Description

This file contains definition and related methods for the FITS header structure. This structure is meant to remain opaque to the user, who only accesses it through the dedicated functions.

The 'keytuple' type is strictly internal to this module. It describes FITS cards as tuples (key,value,comment,line), where key is always a non-NULL character string, value and comment are allowed to be NULL. 'line' is a string containing the line as it has been read from the input FITS file (raw). It is set to NULL if the card is modified later. This allows in output two options: either reconstruct the FITS lines by printing key = value / comment in a FITS-compliant way, or output the lines as they were found in input, except for the modified ones.

The following functions are associated methods to this data structure:

- keytuple_new() constructor
- keytuple_del() destructor
- keytuple_dmp() dumps a keytuple to stdout

## Function Documentation

void qfits_header_add | ( | qfits_header * | hdr,
|  | const char * | key,
|  | const char * | val,
|  | const char * | com,
|  | const char * | lin
| ) |  |

Add a new card to a FITS header.

Parameters:

  hdr | qfits_header object to modify
  key | FITS key
  val | FITS value
  com | FITS comment
  lin | FITS original line if exists

Returns:
  void

This function adds a new card into a header, at the one-before-last position, i.e. the entry just before the END entry if it is there. The key must always be a non-NULL string, all other input parameters are allowed to get NULL values.

void qfits_header_add_after | ( | qfits_header * | hdr,
|  | const char * | after,
|  | const char * | key,
|  | const char * | val,
|  | const char * | com,
|  | const char * | lin
| ) |  |

add a new card to a FITS header

Parameters:

  hdr | qfits_header object to modify
  after | Key to specify insertion place
  key | FITS key
  val | FITS value
  com | FITS comment
  lin | FITS original line if exists

Returns:
  void

Adds a new card to a FITS header, after the specified key. Nothing happens if the specified key is not found in the header. All fields can be NULL, except after and key.

References qfits_expand_keyword().

void qfits_header_append | ( | qfits_header * | hdr,
|  | const char * | key,
|  | const char * | val,
|  | const char * | com,
|  | const char * | lin
| ) |  |

Append a new card to a FITS header.

Parameters:

  hdr | qfits_header object to modify
  key | FITS key
  val | FITS value
  com | FITS comment
  lin | FITS original line if exists

Returns:
  void

Adds a new card in a FITS header as the last one. All fields can be NULL except key.

Referenced by qfits_header_copy(), qfits_header_default(), qfits_header_read_hdr(), qfits_header_read_hdr_string(), qfits_header_readext(), qfits_table_ext_header_default(), and qfits_table_prim_header_default().

qfits_header* qfits_header_copy | ( | const qfits_header * | src | ) |

Copy a FITS header.

Parameters:

  src | Header to replicate

Returns:
  Pointer to newly allocated qfits_header object.

Makes a strict copy of all information contained in the source header. The returned header must be freed using qfits_header_destroy.

References qfits_header_append(), and qfits_header_new().

qfits_header* qfits_header_default | ( | void |  | ) |

FITS header default constructor.

Returns:
  1 newly allocated qfits_header object.

This is a secondary constructor for a qfits_header object. It returns an allocated linked-list handler containing two cards: the first one (SIMPLE=T) and the last one (END).

References qfits_header_append(), and qfits_header_new().

void qfits_header_del | ( | qfits_header * | hdr,
|  | const char * | key
| ) |  |

Delete a card in a FITS header.

Parameters:

  hdr | qfits_header to modify
  key | specifies which card to remove

Returns:
  void

Removes a card from a FITS header. The first found card that matches the key is removed.

References qfits_expand_keyword().

void qfits_header_destroy | ( | qfits_header * | hdr | ) |

qfits_header destructor

Parameters:

  hdr | qfits_header to deallocate

Returns:
  void

Frees all memory associated to a given qfits_header object.

Referenced by qfits_header_read_hdr(), qfits_header_read_hdr_string(), qfits_header_readext(), qfits_header_sort(), qfits_table_ext_header_default(), and qfitsloader_init().

int qfits_header_dump | ( | const qfits_header * | hdr,
|  | FILE * | out
| ) |  |

Dump a FITS header to an opened file.

Parameters:

  hdr | FITS header to dump
  out | Opened file pointer

Returns:
  int 0 if Ok, -1 otherwise Dumps a FITS header to an opened file pointer.

Referenced by qfits_save_table_hdrdump(), and qfits_table_append_xtension_hdr().

int qfits_header_getboolean | ( | const qfits_header * | hdr,
|  | const char * | key,
|  | int | errval
| ) |  |

Return the value associated to a key, as a boolean (int).

Parameters:

  hdr | qfits_header to parse
  key | key to find
  errval | default value to return if nothing is found

Returns:
  int

Finds the value associated to the given key and return it as a boolean. Returns errval if no matching key is found or no value is attached. A boolean is here understood as an int taking the value 0 or 1. errval can be set to any other integer value to reflect that nothing was found.

errval is returned if no matching key is found or no value is attached.

A true value is any character string beginning with a 'y' (yes), a 't' (true) or the digit '1'. A false value is any character string beginning with a 'n' (no), a 'f' (false) or the digit '0'.

References qfits_header_getstr().

char* qfits_header_getcom | ( | const qfits_header * | hdr,
|  | const char * | key
| ) |  |

Return the comment associated to a key, as a string.

Parameters:

  hdr | qfits_header to parse
  key | key to find

Returns:
  pointer to statically allocated string

Finds the comment associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it.

Returns NULL if no matching key is found or no comment is attached.

References qfits_expand_keyword().

double qfits_header_getdouble | ( | const qfits_header * | hdr,
|  | const char * | key,
|  | double | errval
| ) |  |

Return the value associated to a key, as a double.

Parameters:

  hdr | qfits_header to parse
  key | key to find
  errval | default value to return if nothing is found

Returns:
  double

Finds the value associated to the given key and return it as a double. Returns errval if no matching key is found or no value is attached.

References qfits_header_getstr().

int qfits_header_getint | ( | const qfits_header * | hdr,
|  | const char * | key,
|  | int | errval
| ) |  |

Return the value associated to a key, as an int.

Parameters:

  hdr | qfits_header to parse
  key | key to find
  errval | default value to return if nothing is found

Returns:
  int

Finds the value associated to the given key and return it as an int. Returns errval if no matching key is found or no value is attached.

References qfits_header_getstr().

Referenced by qfitsloader_init().

int qfits_header_getitem | ( | const qfits_header * | hdr,
|  | int | idx,
|  | char * | key,
|  | char * | val,
|  | char * | com,
|  | char * | lin
| ) |  |

Return the i-th key/val/com/line tuple in a header.

Parameters:

  hdr | Header to consider
  idx | Index of the requested card
  key | Output key
  val | Output value
  com | Output comment
  lin | Output initial line

Returns:
  int 0 if Ok, -1 if error occurred.

This function is useful to browse a FITS header object card by card. By iterating on the number of cards (available in the 'n' field of the qfits_header struct), you can retrieve the FITS lines and their components one by one. Indexes run from 0 to n-1. You can pass NULL values for key, val, com or lin if you are not interested in a given field.

int i ;
char key[FITS_LINESZ+1] ;
char val[FITS_LINESZ+1] ;
char com[FITS_LINESZ+1] ;
char lin[FITS_LINESZ+1] ;
for (i=0 ; i<hdr->n ; i++) {
qfits_header_getitem(hdr, i, key, val, com, lin);
printf("card[%d] key[%s] val[%s] com[%s]\n", i, key, val, com);
}

This function has primarily been written to interface a qfits_header object to other languages (C++/Python). If you are working within a C program, you should use the other header manipulation routines available in this module.

char* qfits_header_getstr | ( | const qfits_header * | hdr,
|  | const char * | key
| ) |  |

Return the value associated to a key, as a string.

Parameters:

  hdr | qfits_header to parse
  key | key to find

Returns:
  pointer to statically allocated string

Finds the value associated to the given key and return it as a string. The returned pointer is statically allocated, so do not modify its contents or try to free it.

Returns NULL if no matching key is found or no value is attached.

References qfits_expand_keyword().

Referenced by qfits_header_getboolean(), qfits_header_getdouble(), qfits_header_getint(), and qfitsloader_init().

void qfits_header_mod | ( | qfits_header * | hdr,
|  | const char * | key,
|  | const char * | val,
|  | const char * | com
| ) |  |

Modifies a FITS card.

Parameters:

  hdr | qfits_header to modify
  key | FITS key
  val | FITS value
  com | FITS comment

Returns:
  void

Finds the first card in the header matching 'key', and replaces its value and comment fields by the provided values. The initial FITS line is set to NULL in the card.

References qfits_expand_keyword().

qfits_header* qfits_header_new | ( | void |  | ) |

FITS header constructor.

Returns:
  1 newly allocated (empty) qfits_header object.

This is the main constructor for a qfits_header object. It returns an allocated linked-list handler with an empty card list.

Referenced by qfits_header_copy(), qfits_header_default(), qfits_header_read_hdr(), qfits_header_read_hdr_string(), qfits_header_readext(), qfits_header_sort(), qfits_table_ext_header_default(), and qfits_table_prim_header_default().

int qfits_header_sort | ( | qfits_header ** | hdr | ) |

Sort a FITS header.

Parameters:

  hdr | Header to sort (modified)

Returns:
  -1 in error case, 0 otherwise

References qfits_header_destroy(), and qfits_header_new().