|
WCSLIB 8.2.2
|
#include "wcsconfig.h"Go to the source code of this file.
Data Structures | |
| struct | fitskeyid |
| Keyword indexing. More... | |
| struct | fitskey |
| Keyword/value information. More... | |
Macros | |
| #define | FITSHDR_KEYWORD 0x01 |
| Flag bit indicating illegal keyword syntax. | |
| #define | FITSHDR_KEYVALUE 0x02 |
| Flag bit indicating illegal keyvalue syntax. | |
| #define | FITSHDR_COMMENT 0x04 |
| Flag bit indicating illegal keycomment syntax. | |
| #define | FITSHDR_KEYREC 0x08 |
| Flag bit indicating illegal keyrecord. | |
| #define | FITSHDR_CARD 0x08 |
| Deprecated. | |
| #define | FITSHDR_TRAILER 0x10 |
| Flag bit indicating keyrecord following a valid END keyrecord. | |
| #define | KEYIDLEN (sizeof(struct fitskeyid)/sizeof(int)) |
| #define | KEYLEN (sizeof(struct fitskey)/sizeof(int)) |
Typedefs | |
| typedef int | int64[3] |
| 64-bit signed integer data type. | |
Enumerations | |
| enum | fitshdr_errmsg_enum { FITSHDRERR_SUCCESS = 0 , FITSHDRERR_NULL_POINTER = 1 , FITSHDRERR_MEMORY = 2 , FITSHDRERR_FLEX_PARSER = 3 , FITSHDRERR_DATA_TYPE = 4 } |
Functions | |
| int | fitshdr (const char header[], int nkeyrec, int nkeyids, struct fitskeyid keyids[], int *nreject, struct fitskey **keys) |
| FITS header parser routine. | |
Variables | |
| const char * | fitshdr_errmsg [] |
| Status return messages. | |
The Flexible Image Transport System (FITS), is a data format widely used in astronomy for data interchange and archive. It is described in
See also http:
fitshdr() is a generic FITS header parser provided to handle keyrecords that are ignored by the WCS header parsers, wcspih() and wcsbth(). Typically the latter may be set to remove WCS keyrecords from a header leaving fitshdr() to handle the remainder.
| #define FITSHDR_KEYWORD 0x01 |
Flag bit indicating illegal keyword syntax.
Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keyword syntax.
| #define FITSHDR_KEYVALUE 0x02 |
Flag bit indicating illegal keyvalue syntax.
Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keyvalue syntax.
| #define FITSHDR_COMMENT 0x04 |
Flag bit indicating illegal keycomment syntax.
Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keycomment syntax.
| #define FITSHDR_KEYREC 0x08 |
Flag bit indicating illegal keyrecord.
Bit mask for the status flag bit-vector returned by fitshdr() indicating an illegal keyrecord, e.g. an END keyrecord with trailing text.
| #define FITSHDR_CARD 0x08 |
Deprecated.
| #define FITSHDR_TRAILER 0x10 |
Flag bit indicating keyrecord following a valid END keyrecord.
Bit mask for the status flag bit-vector returned by fitshdr() indicating a keyrecord following a valid END keyrecord.
| #define KEYIDLEN (sizeof(struct fitskeyid)/sizeof(int)) |
| #define KEYLEN (sizeof(struct fitskey)/sizeof(int)) |
| int64 |
64-bit signed integer data type.
64-bit signed integer data type defined via preprocessor macro WCSLIB_INT64 which may be defined in wcsconfig.h. For example
This is typedef'd in fitshdr.h as
See fitskey::type.
| enum fitshdr_errmsg_enum |
| int fitshdr | ( | const char | header[], |
| int | nkeyrec, | ||
| int | nkeyids, | ||
| struct fitskeyid | keyids[], | ||
| int * | nreject, | ||
| struct fitskey ** | keys | ||
| ) |
FITS header parser routine.
fitshdr() parses a character array containing a FITS header, extracting all keywords and their values into an array of fitskey structs.
| [in] | header | Character array containing the (entire) FITS header, for example, as might be obtained conveniently via the CFITSIO routine fits_hdr2str(). Each header "keyrecord" (formerly "card image") consists of exactly 80 7-bit ASCII printing characters in the range 0x20 to 0x7e (which excludes NUL, BS, TAB, LF, FF and CR) especially noting that the keyrecords are NOT null-terminated. |
| [in] | nkeyrec | Number of keyrecords in header[]. |
| [in] | nkeyids | Number of entries in keyids[]. |
| [in,out] | keyids | While all keywords are extracted from the header, keyids[] provides a convienient way of indexing them. The fitskeyid struct contains three members; fitskeyid::name must be set by the user while fitskeyid::count and fitskeyid::idx are returned by fitshdr(). All matched keywords will have their fitskey::keyno member negated. |
| [out] | nreject | Number of header keyrecords rejected for syntax errors. |
| [out] | keys | Pointer to an array of nkeyrec fitskey structs containing all keywords and keyvalues extracted from the header. Memory for the array is allocated by fitshdr() and this must be freed by the user. See wcsdealloc(). |
Notes:
Keyword parsing is done in accordance with the syntax defined by NOST 100-2.0, noting the following points in particular:
Sect. 5.1.2.1 specifies that keywords be left-justified in columns 1-8, blank-filled with no embedded spaces, composed only of the ASCII characters ABCDEFGHJKLMNOPQRSTUVWXYZ0123456789-_
fitshdr() accepts any characters in columns 1-8 but flags keywords that do not conform to standard syntax.
Sect. 5.1.2.2 defines the "value indicator" as the characters ''= '' occurring in columns 9 and 10. If these are absent then the keyword has no value and columns 9-80 may contain any ASCII text (but see note 2 for CONTINUE keyrecords). This is copied to the comment member of the fitskey struct.
Sect. 5.1.2.3 states that a keyword may have a null (undefined) value if the value/comment field, columns 11-80, consists entirely of spaces, possibly followed by a comment.
Sect. 5.1.1 states that trailing blanks in a string keyvalue are not significant and the parser always removes them. A string containing nothing but blanks will be replaced with a single blank.
Sect. 5.2.1 also states that a quote character (') in a string value is to be represented by two successive quote characters and the parser removes the repeated quote.
The parser recognizes free-format character (NOST 100-2.0, Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values (Sect. 5.2.4) for all keywords.
Sect. 5.2.3 offers no comment on the size of an integer keyvalue except indirectly in limiting it to 70 digits. The parser will translate an integer keyvalue to a 32-bit signed integer if it lies in the range -2147483648 to +2147483647, otherwise it interprets it as a 64-bit signed integer if possible, or else a "very long" integer (see fitskey::type).
END not followed by 77 blanks is not considered to be a legitimate end keyrecord. The parser supports a generalization of the OGIP Long String Keyvalue Convention (v1.0) whereby strings may be continued onto successive header keyrecords. A keyrecord contains a segment of a continued string if and only if
it contains the pseudo-keyword CONTINUE,
columns 9 and 10 are both blank,
columns 11 to 80 contain what would be considered a valid string keyvalue, including optional keycomment, if column 9 had contained '=',
CONTINUE keyrecord. If any of these conditions is violated, the keyrecord is considered in isolation.
Syntax errors in keycomments in a continued string are treated more permissively than usual; the '/' delimiter may be omitted provided that parsing of the string keyvalue is not compromised. However, the FITSHDR_COMMENT status bit will be set for the keyrecord (see fitskey::status).
As for normal strings, trailing blanks in a continued string are not significant.
In the OGIP convention "the '&' character is used as the last non-blank character of the string to indicate that the string is (probably) continued on the following keyword". This additional syntax is not required by fitshdr(), but if '&' does occur as the last non-blank character of a continued string keyvalue then it will be removed, along with any trailing blanks. However, blanks that occur before the '&' will be preserved.
|
extern |
Status return messages.
Error messages to match the status value returned from each function.
1.9.8