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 data type of the keyword value and can have one of the following symbolic constant values: TSTRING, TLOGICAL (== int), TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TULONG, TLONGLONG, TFLOAT, TDOUBLE, TCOMPLEX, and TDBLCOMPLEX. Within the context of this routine, TSTRING corresponds to a 'char*' data type, 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 data type. 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 data type of the keyword. The third routine returns the entire 80-character header record of the keyword, with any trailing blank characters stripped off. The fourth routine returns the (next) header record that contains the literal string of characters specified by the 'string' argument.

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)

  int fits_read_str / ffgstr
      (fitsfile *fptr, char *string, > char *card, int *status)

3

Read a string-valued keyword and return the string length, the value string, and/or the commment length and comment field. These routines support the reading of long string keyword values of arbitrary length which use the CONTINUE convention. The first two routines, ffgkcsl and ffgskyc are the newer versions of the second two. They provide all the functionality of the older routines, but have the added capability of returning the length of comment strings (if any), and reading multi-line comment strings of arbitrary length. They are recommended for use in the future. ffgksl and ffgsky are maintained for backwards-compatibility.

The first routine, ffgkcsl, simply returns the lengths of the character string value and comment string (if any) of the specified keyword. These lengths are particularly helpful for allocating dynamic memory when retrieving the strings in the ffgskyc function. To create an array large enough to hold the full string, one should allocate a size equal to the returned length + 1 (for the trailing NULL).

The second routine, ffgskyc, is for retrieving the value string and optional comment string, both of which may be of arbitrary length spreading over multiple lines with the CONTINUE keyword convention. It will return up to maxchar characters of the keyword value string, starting with the firstchar character. Similarly, maxcomchar determines the maximum number of characters to return for the comment string. (The valuelen and comlen arguments return the total length of their respective strings regardless of what is actually returned as determined from the firstchar and max(com)char arguments.) If NULL is passed for either the value or comm string pointer, its max(com)char setting is irrelevant since the corresponding string will not be returned.

The ffgksl routine is the earlier version of ffgkcsl. It only returns the value string length and not the comment string length. ffgsky, the earlier version of ffgskyc, does return both the value string and comment string. However it will only return up to the first FLEN_COMMENT-1 characters of the comment. It can read comments across multiple lines, but not of arbitrary length.

  int fits_get_key_com_strlen / ffgkcsl
      (fitsfile *fptr, const char *keyname, int *length, int *comlength,
      int *status);
      
  int fits_read_string_key_com / ffgskyc
      (fitsfile *fptr, const char *keyname, int firstchar, int maxchar,
      int maxcomchar, char *value, int *valuelen, char *comm,
      int *comlen, int *status);
      
  int fits_get_key_strlen / ffgksl
      (fitsfile *fptr, const char *keyname, int *length, int *status);

  int fits_read_string_key / ffgsky
       (fitsfile *fptr, const char *keyname, int firstchar, int maxchar,
       char *value, int *valuelen, char *comm, int *status);

4

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 (with trailing blanks truncated), while the second routine parses the record and returns the name, value, and comment fields as separate (blank truncated) 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)

5

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)

6

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)

7

Concatenate the header keywords in the CHDU into a single long string of characters. This provides a convenient way of passing all or part of the header information in a FITS HDU to other subroutines. Each 80-character fixed-length keyword record is appended to the output character string, in order, with no intervening separator or terminating characters. The last header record is terminated with a NULL character. These routine allocates memory for the returned character array, so the calling program must free the memory when finished. The cleanest way to do this is to call the fits_free_memory routine.

There are 2 related routines: fits_hdr2str simply concatenates all the existing keywords in the header; fits_convert_hdr2str is similar, except that if the CHDU is a tile compressed image (stored in a binary table) then it will first convert that header back to that of the corresponding normal FITS image before concatenating the keywords.

Selected keywords may be excluded from the returned character string. If the second parameter (nocomments) is TRUE (nonzero) then any COMMENT, HISTORY, or blank keywords in the header will not be copied to the output string.

The 'exclist' parameter may be used to supply a list of keywords that are to be excluded from the output character string. Wild card characters (*, ?, and #) may be used in the excluded keyword names. If no additional keywords are to be excluded, then set nexc = 0 and specify NULL for the the **exclist parameter.

  int fits_hdr2str / ffhdr2str
      (fitsfile *fptr, int nocomments, char **exclist, int nexc,
      > char **header, int *nkeys, int *status)

  int fits_convert_hdr2str / ffcnvthdr2str
      (fitsfile *fptr, int nocomments, char **exclist, int nexc,
      > char **header, int *nkeys, int *status)

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