Header Keyword Read/Write Routines

These routines read or write keywords in the Current Header Unit (CHU). Wild card characters (*, ?, or #) may be used when specifying the name of the keyword to be read: a '?' will match any single character at that position in the keyword name and a '*' will match any length (including zero) string of characters. The '#' character will match any consecutive string of decimal digits (0 - 9). When a wild card is used the routine will only search for a match from the current header position to the end of the header and will not resume the search from the top of the header back to the original header position as is done when no wildcards are included in the keyword name. The fits_read_record routine may be used to set the starting position when doing wild card searchs. A status value of KEY_NO_EXIST is returned if the specified keyword to be read is not found in the header.

1

Return the number of existing keywords (not counting the END keyword) and the amount of space currently available for more keywords. It returns morekeys = -1 if the header has not yet been closed. Note that CFITSIO will dynamically add space if required when writing new keywords to a header so in practice there is no limit to the number of keywords that can be added to a header. A null pointer may be entered for the morekeys parameter if it's value is not needed.  

  int fits_get_hdrspace / ffghsp
      (fitsfile *fptr, > int *keysexist, int *morekeys, int *status)

2

Write (append) a new keyword of the appropriate datatype into the CHU. Note that the address to the value, and not the value itself, must be entered. The datatype parameter specifies the datatype of the keyword value with one of the following values: TSTRING, TLOGICAL (== int), TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TFLOAT, TDOUBLE. A null pointer may be entered for the comment parameter which will cause the comment field to be left blank.  

  int fits_write_key / ffpky
      (fitsfile *fptr, int datatype, char *keyname, DTYPE *value,
          char *comment, > int *status)

3

Write (update) a keyword of the appropriate datatype into the CHU. This routine will modify the value and comment field if the keyword already exists in the header, otherwise it will append a new keyword at the end of the header. Note that the address to the value, and not the value itself, must be entered. The datatype parameter specifies the datatype of the keyword value and can have one of the following values: TSTRING, TLOGICAL (== int), TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TFLOAT, TDOUBLE, TCOMPLEX, and TDBLCOMPLEX. A null pointer may be entered for the comment parameter which will leave the comment field blank (or unmodified).  

  int fits_update_key / ffuky
      (fitsfile *fptr, int datatype, char *keyname, DTYPE *value,
          char *comment, > int *status)

4

Write a keyword with a null or undefined value (i.e., the value field in the keyword is left blank). This routine will modify the value and comment field if the keyword already exists in the header, otherwise it will append a new null-valued keyword at the end of the header. A null pointer may be entered for the comment parameter which will leave the comment field blank (or unmodified).  

  int fits_update_key_null / ffukyu
      (fitsfile *fptr, char *keyname, char *comment, > int *status)

5

Write (append) a COMMENT keyword to the CHU. The comment string will be split over multiple COMMENT keywords if it is longer than 70 characters.  

  int fits_write_comment / ffpcom
      (fitsfile *fptr, char *comment, > int *status)

6

Write (append) a HISTORY keyword to the CHU. The comment string will be split over multiple HISTORY keywords if it is longer than 70 characters.  

  int fits_write_history / ffphis
      (fitsfile *fptr, char *history, > int *status)

7

Write the DATE keyword to the CHU. The keyword value will contain the current system date as a character string in 'yyyy-mm-ddThh:mm:ss' format. If a DATE keyword already exists in the header, then this routine will simply update the keyword value with the current date.  

  int fits_write_date / ffpdat
      (fitsfile *fptr, > int *status)

8

Write a user specified keyword record into the CHU. This is a low-level routine which can be used to write any arbitrary record into the header. The record must conform to the all the FITS format requirements.  

  int fits_write_record / ffprec
      (fitsfile *fptr, char *card, > int *status)

9

Update an 80-character record in the CHU. If a keyword with the input name already exists, then it is overwritten by the value of card. This could modify the keyword name as well as the value and comment fields. If the keyword doesn't already exist then a new keyword card is appended to the header.  

  int fits_update_card / ffucrd
      (fitsfile *fptr, char *keyname, char *card, > int *status)

10

Write the physical units string into an existing keyword. This routine uses a local convention, shown in the following example, in which the keyword units are enclosed in square brackets in the beginning of the keyword comment field.  

  VELOCITY=                 12.3 / [km/s] orbital speed

  int fits_write_key_unit / ffpunt
      (fitsfile *fptr, char *keyname, char *unit, > int *status)

11

Rename an existing keyword preserving the current value and comment fields.  

  int fits_modify_name / ffmnam
      (fitsfile *fptr, char *oldname, char *newname, > int *status)

12

Modify (overwrite) the comment field of an existing keyword.  

  int fits_modify_comment / ffmcom
      (fitsfile *fptr, char *keyname, char *comment, > int *status)

13

Read the nth header record in the CHU. The first keyword in the header is at keynum = 1; if keynum = 0 then this routine simply moves the internal CFITSIO pointer to the beginning of the header so that subsequent keyword operations will start at the top of the header (e.g., prior to searching for keywords using wild cards in the keyword name).  

  int fits_read_record / ffgrec
      (fitsfile *fptr, int keynum, > char *card, int *status)

14

Read the header record having the specified keyword name.  

  int fits_read_card / ffgcrd
      (fitsfile *fptr, char *keyname, > char *card, int *status)

15

Read a specified keyword value and comment. The datatype parameter specifies the returned datatype of the 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 keyword value does not have the same datatype. If the value of the keyword is undefined (i.e., the value field is blank) then an error status = VALUE_UNDEFINED will be returned. If a NULL comment pointer is given on input then the comment string will not be returned.  

  int fits_read_key / ffgky
      (fitsfile *fptr, int datatype, char *keyname, > DTYPE *value,
       char *comment, int *status)

16

Read the physical units string in an existing keyword. This routine uses a local convention, shown in the following example, in which the keyword units are enclosed in square brackets in the beginning of the keyword comment field. A null string is returned if no units are defined for the keyword.  

  VELOCITY=                 12.3 / [km/s] orbital speed

  int fits_read_key_unit / ffgunt
      (fitsfile *fptr, char *keyname, > char *unit, int *status)

17

Delete a keyword record. The space previously occupied by the keyword is reclaimed by moving all the following header records up one row in the header. The first routine deletes a keyword at a specified position in the header (the first keyword is at position 1), whereas the second routine deletes a specifically named keyword. Wild card characters may be used when specifying the name of the keyword to be deleted.    

  int fits_delete_record / ffdrec
      (fitsfile *fptr, int   keynum,  > int *status)

  int fits_delete_key / ffdkey
      (fitsfile *fptr, char *keyname, > int *status)