9.3.5 Read Keyword Routines

Wild card characters may be used when specifying the name of the keyword to be read.

1

Read a keyword value (with the appropriate data type) and comment from the CHU. If a NULL comment pointer is given on input, then the comment string will not be returned. If the value of the keyword is not defined (i.e., the value field is blank) then an error status = VALUE_UNDEFINED will be returned and the input value will not be changed (except that ffgkys will reset the value to a null string).

  int fits_read_key_str / ffgkys
      (fitsfile *fptr, char *keyname, > char *value, char *comment,
       int *status);

  NOTE: after calling the following routine, programs must explicitly free
        the memory allocated for 'longstr' after it is no longer needed by
        calling fits_free_memory.

  int fits_read_key_longstr / ffgkls
      (fitsfile *fptr, char *keyname, > char **longstr, char *comment,
             int *status)

  int fits_free_memory / fffree
      (char *longstr, > int *status);

  int fits_read_key_[log, lng, flt, dbl, cmp, dblcmp] / ffgky[ljedcm]
      (fitsfile *fptr, char *keyname, > DTYPE *numval, char *comment,
       int *status)

  int fits_read_key_lnglng / ffgkyjj
      (fitsfile *fptr, char *keyname, > LONGLONG *numval, char *comment,
       int *status)

2

Read a sequence of indexed keyword values (e.g., NAXIS1, NAXIS2, ...). The input starting index number (nstart) must be greater than 0. If the value of any of the keywords is not defined (i.e., the value field is blank) then an error status = VALUE_UNDEFINED will be returned and the input value for the undefined keyword(s) will not be changed. These routines do not support wild card characters in the root name. If there are no indexed keywords in the header with the input root name then these routines do not return a non-zero status value and instead simply return nfound = 0.

  int fits_read_keys_str / ffgkns
      (fitsfile *fptr, char *keyname, int nstart, int nkeys,
       > char **value, int *nfound,  int *status)

  int fits_read_keys_[log, lng, flt, dbl] / ffgkn[ljed]
      (fitsfile *fptr, char *keyname, int nstart, int nkeys,
       > DTYPE *numval, int *nfound, int *status)

3

Read the value of a floating point keyword, returning the integer and fractional parts of the value in separate routine arguments. This routine may be used to read any keyword but is especially useful for reading the 'triple precision' keywords written by ffpkyt.

  int fits_read_key_triple / ffgkyt
      (fitsfile *fptr, char *keyname, > long *intval, double *frac,
       char *comment, int *status)