FITSIO Home
Next: 5.4.2 Keyword Writing Routines
Up: 5.4 Header Keyword Read/Write
Previous: 5.4 Header Keyword Read/Write
Contents
- 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.
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 (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)
- 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)
- 6
- 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. This routine allocates memory for the returned
character array, so the calling program must free the memory when
finished.
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 **header parameter.
int fits_hdr2str
(fitsfile *fptr, int nocomments, char **exclist, int nexc,
> char **header, int *nkeys, int *status)
FITSIO Home
Next: 5.4.2 Keyword Writing Routines
Up: 5.4 Header Keyword Read/Write
Previous: 5.4 Header Keyword Read/Write
Contents