5.4.1 Keyword Reading Routines

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

Return the specified keyword. In the first routine, the datatype parameter specifies the desired 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. Within the context of this routine, TSTRING corresponds to a 'char*' datatype, i.e., a pointer to a character array. 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.

The second routine returns the keyword value as a character string (a literal copy of what is in the value field) regardless of the intrinsic datatype of the keyword. The third routine returns the entire 80-character header record of the keyword.

If a NULL comment pointer is supplied 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)

  int fits_read_keyword / ffgkey
      (fitsfile *fptr, char *keyname, > char *value, char *comment,
       int *status)

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

3

Return the nth header record in the CHU. The first keyword in the header is at keynum = 1; if keynum = 0 then these routines simply reset 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). The first routine returns the entire 80-character header record, while the second routine parses the record and returns the name, value, and comment fields as separate character strings. If a NULL comment pointer is given on input, then the comment string will not be returned.    

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

  int fits_read_keyn / ffgkyn
      (fitsfile *fptr, int keynum, > char *keyname, char *value,
       char *comment, int *status)

4

Return the next keyword whose name matches one of the strings in 'inclist' but does not match any of the strings in 'exclist'. The strings in inclist and exclist may contain wild card characters (*, ?, and #) as described at the beginning of this section. This routine searches from the current header position to the end of the header, only, and does not continue the search from the top of the header back to the original position. The current header position may be reset with the ffgrec routine. Note that nexc may be set = 0 if there are no keywords to be excluded. This routine returns status = KEY_NO_EXIST if a matching keyword is not found.  

  int fits_find_nextkey / ffgnxk
      (fitsfile *fptr, char **inclist, int ninc, char **exclist,
       int nexc, > char *card, int  *status)

5

Return the physical units string from 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)