# fitshdr.h File Reference

`#include "wcsconfig.h"`

Go to the source code of this file.

## Data Structures
struct | fitskeyid
| Keyword indexing. More...
struct | fitskey
| Keyword/value information. More...
## Defines
#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.
## 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.

## Detailed Description

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 Documentation

#define FITSHDR_KEYWORD 0x01

Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keyword syntax.

#define FITSHDR_KEYVALUE 0x02

Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keyvalue syntax.

#define FITSHDR_COMMENT 0x04

Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keycomment syntax.

#define FITSHDR_KEYREC 0x08

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:
  Added for backwards compatibility, use FITSHDR_KEYREC instead.

#define FITSHDR_TRAILER 0x10

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))

## Typedef Documentation

int64

64-bit signed integer data type defined via preprocessor macro WCSLIB_INT64 which may be defined in wcsconfig.h. For example

       #define WCSLIB_INT64 long long int

This is typedef'd in fitshdr.h as

       #ifdef WCSLIB_INT64
         typedef WCSLIB_INT64 int64;
       #else
         typedef int int64[3];
       #endif

See fitskey::type.

## Function Documentation

int fitshdr | ( | const char | header[],
|  | int | nkeyrec,
|  | int | nkeyids,
|  | struct fitskeyid | keyids[],
|  | int * | nreject,
|  | struct fitskey ** | keys |
| ) |  |  |

fitshdr() parses a character array containing a FITS header, extracting all keywords and their values into an array of fitskey structs.

Parameters:

  `[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::name 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 by invoking free() on the array.

Returns:
  Status return value:
  - 0: Success.
  - 1: Null fitskey pointer passed.
  - 2: Memory allocation failed.
  - 3: Fatal error returned by Flex parser.

Notes:

1. Keyword parsing is done in accordance with the syntax defined by NOST 100-2.0, noting the following points in particular:

   1. 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.

   2. 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.

   3. 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.

   4. 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.

   5. 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.

   6. 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 translates 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).

   7. ``END`` not followed by 77 blanks is not considered to be a legitimate end keyrecord.

2. 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

   1. it contains the pseudo-keyword `CONTINUE`,

   2. columns 9 and 10 are both blank,

   3. columns 11 to 80 contain what would be considered a valid string keyvalue, including optional keycomment, if column 9 had contained '`=`',

   4. the previous keyrecord contained either a valid string keyvalue or a valid `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.

## Variable Documentation

const char * fitshdr_errmsg[]

Error messages to match the status value returned from each function.