/usr/include/wcslib-5.18/fitshdr.h is in wcslib-dev 5.18-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 | /*============================================================================
WCSLIB 5.18 - an implementation of the FITS WCS standard.
Copyright (C) 1995-2018, Mark Calabretta
This file is part of WCSLIB.
WCSLIB is free software: you can redistribute it and/or modify it under the
terms of the GNU Lesser General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.
WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
more details.
You should have received a copy of the GNU Lesser General Public License
along with WCSLIB. If not, see http://www.gnu.org/licenses.
Direct correspondence concerning WCSLIB to mark@calabretta.id.au
Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
http://www.atnf.csiro.au/people/Mark.Calabretta
$Id: fitshdr.h,v 5.18 2018/01/10 08:32:14 mcalabre Exp $
*=============================================================================
*
* WCSLIB 5.18 - C routines that implement the FITS World Coordinate System
* (WCS) standard. Refer to the README file provided with WCSLIB for an
* overview of the library.
*
*
* Summary of the fitshdr routines
* -------------------------------
* The Flexible Image Transport System (FITS), is a data format widely used in
* astronomy for data interchange and archive. It is described in
*
= "Definition of the Flexible Image Transport System (FITS), version 3.0",
= Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
= A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362
*
* See also http://fits.gsfc.nasa.gov
*
* 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.
*
*
* fitshdr() - 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.
*
* Given:
* header const char []
* 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.
*
* nkeyrec int Number of keyrecords in header[].
*
* nkeyids int Number of entries in keyids[].
*
* Given and returned:
* keyids struct fitskeyid []
* 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.
*
* Returned:
* nreject int* Number of header keyrecords rejected for syntax
* errors.
*
* keys struct fitskey**
* 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.
*
* Function return value:
* int 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:
*
* a: 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.
*
* b: 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.
*
* c: 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.
*
* d: 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.
*
* e: 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.
*
* f: 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).
*
* g: 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
*
* a: it contains the pseudo-keyword CONTINUE,
*
* b: columns 9 and 10 are both blank,
*
* c: columns 11 to 80 contain what would be considered a valid string
* keyvalue, including optional keycomment, if column 9 had contained
* '=',
*
* d: 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.
*
*
* fitskeyid struct - Keyword indexing
* -----------------------------------
* fitshdr() uses the fitskeyid struct to return indexing information for
* specified keywords. The struct contains three members, the first of which,
* fitskeyid::name, must be set by the user with the remainder returned by
* fitshdr().
*
* char name[12]:
* (Given) Name of the required keyword. This is to be set by the user;
* the '.' character may be used for wildcarding. Trailing blanks will be
* replaced with nulls.
*
* int count:
* (Returned) The number of matches found for the keyword.
*
* int idx[2]:
* (Returned) Indices into keys[], the array of fitskey structs returned by
* fitshdr(). Note that these are 0-relative array indices, not keyrecord
* numbers.
*
* If the keyword is found in the header the first index will be set to the
* array index of its first occurrence, otherwise it will be set to -1.
*
* If multiples of the keyword are found, the second index will be set to
* the array index of its last occurrence, otherwise it will be set to -1.
*
*
* fitskey struct - Keyword/value information
* ------------------------------------------
* fitshdr() returns an array of fitskey structs, each of which contains the
* result of parsing one FITS header keyrecord. All members of the fitskey
* struct are returned by fitshdr(), none are given by the user.
*
* int keyno
* (Returned) Keyrecord number (1-relative) in the array passed as input to
* fitshdr(). This will be negated if the keyword matched any specified in
* the keyids[] index.
*
* int keyid
* (Returned) Index into the first entry in keyids[] with which the
* keyrecord matches, else -1.
*
* int status
* (Returned) Status flag bit-vector for the header keyrecord employing the
* following bit masks defined as preprocessor macros:
*
* - FITSHDR_KEYWORD: Illegal keyword syntax.
* - FITSHDR_KEYVALUE: Illegal keyvalue syntax.
* - FITSHDR_COMMENT: Illegal keycomment syntax.
* - FITSHDR_KEYREC: Illegal keyrecord, e.g. an END keyrecord with
* trailing text.
* - FITSHDR_TRAILER: Keyrecord following a valid END keyrecord.
*
* The header keyrecord is syntactically correct if no bits are set.
*
* char keyword[12]
* (Returned) Keyword name, null-filled for keywords of less than eight
* characters (trailing blanks replaced by nulls).
*
* Use
*
= sprintf(dst, "%.8s", keyword)
*
* to copy it to a character array with null-termination, or
*
= sprintf(dst, "%8.8s", keyword)
*
* to blank-fill to eight characters followed by null-termination.
*
* int type
* (Returned) Keyvalue data type:
* - 0: No keyvalue (both the value and type are undefined).
* - 1: Logical, represented as int.
* - 2: 32-bit signed integer.
* - 3: 64-bit signed integer (see below).
* - 4: Very long integer (see below).
* - 5: Floating point (stored as double).
* - 6: Integer complex (stored as double[2]).
* - 7: Floating point complex (stored as double[2]).
* - 8: String.
* - 8+10*n: Continued string (described below and in fitshdr() note 2).
*
* A negative type indicates that a syntax error was encountered when
* attempting to parse a keyvalue of the particular type.
*
* Comments on particular data types:
* - 64-bit signed integers lie in the range
*
= (-9223372036854775808 <= int64 < -2147483648) ||
= (+2147483647 < int64 <= +9223372036854775807)
*
* A native 64-bit data type may be defined via preprocessor macro
* WCSLIB_INT64 defined in wcsconfig.h, e.g. as 'long long int'; this
* will be typedef'd to 'int64' here. If WCSLIB_INT64 is not set, then
* int64 is typedef'd to int[3] instead and fitskey::keyvalue is to be
* computed as
*
= ((keyvalue.k[2]) * 1000000000 +
= keyvalue.k[1]) * 1000000000 +
= keyvalue.k[0]
*
* and may reported via
*
= if (keyvalue.k[2]) {
= printf("%d%09d%09d", keyvalue.k[2], abs(keyvalue.k[1]),
= abs(keyvalue.k[0]));
= } else {
= printf("%d%09d", keyvalue.k[1], abs(keyvalue.k[0]));
= }
*
* where keyvalue.k[0] and keyvalue.k[1] range from -999999999 to
* +999999999.
*
* - Very long integers, up to 70 decimal digits in length, are encoded
* in keyvalue.l as an array of int[8], each of which stores 9 decimal
* digits. fitskey::keyvalue is to be computed as
*
= (((((((keyvalue.l[7]) * 1000000000 +
= keyvalue.l[6]) * 1000000000 +
= keyvalue.l[5]) * 1000000000 +
= keyvalue.l[4]) * 1000000000 +
= keyvalue.l[3]) * 1000000000 +
= keyvalue.l[2]) * 1000000000 +
= keyvalue.l[1]) * 1000000000 +
= keyvalue.l[0]
*
* - Continued strings are not reconstructed, they remain split over
* successive fitskey structs in the keys[] array returned by
* fitshdr(). fitskey::keyvalue data type, 8 + 10n, indicates the
* segment number, n, in the continuation.
*
* int padding
* (An unused variable inserted for alignment purposes only.)
*
* union keyvalue
* (Returned) A union comprised of
*
* - fitskey::i,
* - fitskey::k,
* - fitskey::l,
* - fitskey::f,
* - fitskey::c,
* - fitskey::s,
*
* used by the fitskey struct to contain the value associated with a
* keyword.
*
* int i
* (Returned) Logical (fitskey::type == 1) and 32-bit signed integer
* (fitskey::type == 2) data types in the fitskey::keyvalue union.
*
* int64 k
* (Returned) 64-bit signed integer (fitskey::type == 3) data type in the
* fitskey::keyvalue union.
*
* int l[8]
* (Returned) Very long integer (fitskey::type == 4) data type in the
* fitskey::keyvalue union.
*
* double f
* (Returned) Floating point (fitskey::type == 5) data type in the
* fitskey::keyvalue union.
*
* double c[2]
* (Returned) Integer and floating point complex (fitskey::type == 6 || 7)
* data types in the fitskey::keyvalue union.
*
* char s[72]
* (Returned) Null-terminated string (fitskey::type == 8) data type in the
* fitskey::keyvalue union.
*
* int ulen
* (Returned) Where a keycomment contains a units string in the standard
* form, e.g. [m/s], the ulen member indicates its length, inclusive of
* square brackets. Otherwise ulen is zero.
*
* char comment[84]
* (Returned) Keycomment, i.e. comment associated with the keyword or, for
* keyrecords rejected because of syntax errors, the compete keyrecord
* itself with null-termination.
*
* Comments are null-terminated with trailing spaces removed. Leading
* spaces are also removed from keycomments (i.e. those immediately
* following the '/' character), but not from COMMENT or HISTORY keyrecords
* or keyrecords without a value indicator ("= " in columns 9-80).
*
*
* Global variable: const char *fitshdr_errmsg[] - Status return messages
* ----------------------------------------------------------------------
* Error messages to match the status value returned from each function.
*
*===========================================================================*/
#ifndef WCSLIB_FITSHDR
#define WCSLIB_FITSHDR
#include "wcsconfig.h"
#ifdef __cplusplus
extern "C" {
#endif
#define FITSHDR_KEYWORD 0x01
#define FITSHDR_KEYVALUE 0x02
#define FITSHDR_COMMENT 0x04
#define FITSHDR_KEYREC 0x08
#define FITSHDR_CARD 0x08 /* Alias for backwards compatibility. */
#define FITSHDR_TRAILER 0x10
extern const char *fitshdr_errmsg[];
#ifdef WCSLIB_INT64
typedef WCSLIB_INT64 int64;
#else
typedef int int64[3];
#endif
/* Struct used for indexing the keywords. */
struct fitskeyid {
char name[12]; /* Keyword name, null-terminated. */
int count; /* Number of occurrences of keyword. */
int idx[2]; /* Indices into fitskey array. */
};
/* Size of the fitskeyid struct in int units, used by the Fortran wrappers. */
#define KEYIDLEN (sizeof(struct fitskeyid)/sizeof(int))
/* Struct used for storing FITS keywords. */
struct fitskey {
int keyno; /* Header keyrecord sequence number (1-rel).*/
int keyid; /* Index into fitskeyid[]. */
int status; /* Header keyrecord status bit flags. */
char keyword[12]; /* Keyword name, null-filled. */
int type; /* Keyvalue type (see above). */
int padding; /* (Dummy inserted for alignment purposes.) */
union {
int i; /* 32-bit integer and logical values. */
int64 k; /* 64-bit integer values. */
int l[8]; /* Very long signed integer values. */
double f; /* Floating point values. */
double c[2]; /* Complex values. */
char s[72]; /* String values, null-terminated. */
} keyvalue; /* Keyvalue. */
int ulen; /* Length of units string. */
char comment[84]; /* Comment (or keyrecord), null-terminated. */
};
/* Size of the fitskey struct in int units, used by the Fortran wrappers. */
#define KEYLEN (sizeof(struct fitskey)/sizeof(int))
int fitshdr(const char header[], int nkeyrec, int nkeyids,
struct fitskeyid keyids[], int *nreject, struct fitskey **keys);
#ifdef __cplusplus
}
#endif
#endif /* WCSLIB_FITSHDR */
|