1 /*** File fitshead.h FITS header access subroutines 2 *** January 9, 2007 3 *** By Jessica Mink, jmink@cfa.harvard.edu 4 *** Harvard-Smithsonian Center for Astrophysics 5 *** Copyright (C) 1996-2007 6 *** Smithsonian Astrophysical Observatory, Cambridge, MA, USA 7 8 This library is free software; you can redistribute it and/or 9 modify it under the terms of the GNU Lesser General Public 10 License as published by the Free Software Foundation; either 11 version 2 of the License, or (at your option) any later version. 12 13 This library is distributed in the hope that it will be useful, 14 but WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public 19 License along with this library; if not, write to the Free Software 20 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 21 22 Correspondence concerning WCSTools should be addressed as follows: 23 Internet email: jmink@cfa.harvard.edu 24 Postal address: Jessica Mink 25 Smithsonian Astrophysical Observatory 26 60 Garden St. 27 Cambridge, MA 02138 USA 28 */ 29 30 /* Declarations for subroutines in hget.c, hput.c, and iget.c */ 31 32 #ifndef _fitshead_h_ 33 #define _fitshead_h_ 34 35 #include <sys/types.h> 36 37 #ifdef __cplusplus /* C++ prototypes */ 38 extern "C" { 39 #endif 40 41 42 #ifdef __STDC__ /* Full ANSI prototypes */ 43 44 /* Subroutines in hget.c */ 45 int hgeti2( /* Extract short value from FITS header */ 46 const char* hstring, /* FITS header string */ 47 const char* keyword, /* FITS keyword */ 48 short* val); /* short integer value (returned) */ 49 int hgeti4c( /* Extract int value from FITS header */ 50 const char* hstring, /* FITS header string */ 51 const char* keyword, /* FITS keyword */ 52 const char* wchar, /* WCS to use (A-Z or null) */ 53 int* val); /* integer value (returned) */ 54 int hgeti4( /* Extract int value from FITS header */ 55 const char* hstring, /* FITS header string */ 56 const char* keyword, /* FITS keyword */ 57 int* val); /* integer value (returned) */ 58 int hgetr4( /* Extract float value from FITS header */ 59 const char* hstring, /* FITS header string */ 60 const char* keyword, /* FITS keyword */ 61 float* val); /* float value (returned) */ 62 int hgetr8c( /* Extract double value from FITS header */ 63 const char* hstring, /* FITS header string */ 64 const char* keyword, /* FITS keyword */ 65 const char* wchar, /* WCS to use (A-Z or null) */ 66 double* val); /* double value (returned) */ 67 int hgetr8( /* Extract double value from FITS header */ 68 const char* hstring, /* FITS header string */ 69 const char* keyword, /* FITS keyword */ 70 double* val); /* double value (returned) */ 71 int hgetra( /* Extract right ascension from FITS header */ 72 const char* hstring, /* FITS header string */ 73 const char* keyword, /* FITS keyword */ 74 double* ra); /* RA in degrees (returned) */ 75 int hgetdec( /* Extract declination from FITS header */ 76 const char* hstring, /* FITS header string */ 77 const char* keyword, /* FITS keyword */ 78 double* dec); /* Dec in degrees (returned) */ 79 int hgetdate( /* Extract date from FITS header */ 80 const char* hstring, /* FITS header string */ 81 const char* keyword, /* FITS keyword */ 82 double* date); /* Date in fractional years (returned) */ 83 int hgetl( /* Extract boolean value from FITS header */ 84 const char* hstring, /* FITS header string */ 85 const char* keyword, /* FITS keyword */ 86 int* lval); /* 1 if T, 0 if F (returned) */ 87 int hgetsc( /* Extract string value from FITS header */ 88 const char* hstring, /* FITS header string */ 89 const char* keyword, /* FITS keyword */ 90 const char* wchar, /* WCS to use (A-Z or null) */ 91 const int lstr, /* maximum length of returned string */ 92 char* string); /* null-terminated string value (returned) */ 93 int hgets( /* Extract string value from FITS header */ 94 const char* hstring, /* FITS header string */ 95 const char* keyword, /* FITS keyword */ 96 const int lstr, /* maximum length of returned string */ 97 char* string); /* null-terminated string value (returned) */ 98 int hgetm ( /* Extract string from multiple keywords */ 99 const char* hstring, /* FITS header string */ 100 const char* keyword, /* FITS keyword */ 101 const int lstr, /* maximum length of returned string */ 102 char* string); /* null-terminated string value (returned) */ 103 int hgetndec( /* Find number of decimal places in FITS value*/ 104 const char* hstring, /* FITS header string */ 105 const char* keyword, /* FITS keyword */ 106 int* ndec); /* number of decimal places (returned) */ 107 108 char* hgetc( /* Return pointer to value for FITS keyword */ 109 const char* hstring, /* FITS header string */ 110 const char* keyword); /* FITS keyword */ 111 112 char* ksearch( /* Return pointer to keyword in FITS header */ 113 const char* hstring, /* FITS header string */ 114 const char* keyword); /* FITS keyword */ 115 char *blsearch ( 116 const char* hstring, /* FITS header string */ 117 const char* keyword); /* FITS keyword */ 118 119 char *strsrch ( /* Find string s2 within string s1 */ 120 const char* s1, /* String to search */ 121 const char* s2); /* String to look for */ 122 char *strnsrch ( /* Find string s2 within string s1 */ 123 const char* s1, /* String to search */ 124 const char* s2, /* String to look for */ 125 const int ls1); /* Length of string being searched */ 126 127 char *strcsrch ( /* Find string s2 within string s1 (no case) */ 128 const char* s1, /* String to search */ 129 const char* s2); /* String to look for */ 130 char *strncsrch ( /* Find string s2 within string s1 (no case) */ 131 const char* s1, /* String to search */ 132 const char* s2, /* String to look for */ 133 const int ls1); /* Length of string being searched */ 134 135 int hlength( /* Set length of unterminated FITS header */ 136 const char *header, /* FITS header */ 137 const int lhead); /* Allocated length of FITS header */ 138 int gethlength( /* Get length of current FITS header */ 139 char* header); /* FITS header */ 140 141 double str2ra( /* Return RA in degrees from string */ 142 const char* in); /* Character string (hh:mm:ss.sss or dd.dddd) */ 143 double str2dec( /* Return Dec in degrees from string */ 144 const char* in); /* Character string (dd:mm:ss.sss or dd.dddd) */ 145 146 int isnum( /* Return 1 if number, else 0 */ 147 const char* string); /* Character string which may be a number */ 148 int notnum( /* Return 0 if number, else 1 */ 149 const char* string); /* Character string which may be a number */ 150 int numdec( /* Return number of decimal places in number */ 151 const char* string); /* Character string which may be a number */ 152 void strfix( /* Clean up extraneous characters in string */ 153 char* string, /* Character string which may be a number */ 154 int fillblank, /* If 1, blanks are replaced by underscores */ 155 int dropzero); /* If 1, drop trailing zeroes from string */ 156 157 char *getltime(void); /* Return current local time in ISO format */ 158 char *getutime(void); /* Return current UT as an ISO-format string */ 159 160 /* Subroutines in iget.c */ 161 int mgetstr( /* Extract string from multiline FITS keyword */ 162 const char* hstring, /* FITS header string */ 163 const char* mkey, /* FITS keyword root _n added for extra lines */ 164 const char* keyword, /* IRAF keyword */ 165 const int lstr, /* maximum length of returned string */ 166 char* string); /* null-terminated string value (returned) */ 167 int mgeti4( /* Extract int from multiline FITS keyword */ 168 const char* hstring, /* FITS header string */ 169 const char* mkey, /* FITS keyword root _n added for extra lines */ 170 const char* keyword, /* IRAF keyword */ 171 int* ival); /* int keyword value (returned) */ 172 int mgetr8( /* Extract double from multiline FITS keyword */ 173 const char* hstring, /* FITS header string */ 174 const char* mkey, /* FITS keyword root _n added for extra lines */ 175 const char* keyword, /* IRAF keyword */ 176 double* dval); /* double keyword value (returned) */ 177 int igeti4( /* Extract int from IRAF keyword string */ 178 const char* hstring, /* Multiline IRAF keyword string value */ 179 const char* keyword, /* IRAF keyword */ 180 int* val); /* int value (returned) */ 181 int igetr4( /* Extract float from IRAF keyword string */ 182 const char* hstring, /* Multiline IRAF keyword string value */ 183 const char* keyword, /* IRAF keyword */ 184 float* val); /* float value (returned) */ 185 int igetr8( /* Extract double from IRAF keyword string */ 186 const char* hstring, /* Multiline IRAF keyword string value */ 187 const char* keyword, /* IRAF keyword */ 188 double* val); /* double value (returned) */ 189 int igets( /* Extract string from IRAF keyword string */ 190 const char* hstring, /* Multiline IRAF keyword string value */ 191 const char* keyword, /* IRAF keyword */ 192 const int lstr, /* maximum length of returned string */ 193 char* string); /* null-terminated string value (returned) */ 194 char *igetc( /* Extract string from IRAF keyword string */ 195 const char* hstring, /* Multiline IRAF keyword string value */ 196 const char* keyword); /* IRAF keyword */ 197 198 /* Subroutines in hput.c */ 199 /* All hput* routines return 0 if successful, else -1 */ 200 int hputi2( /* Implant short value into FITS header */ 201 char* hstring, /* FITS header string (modified) */ 202 const char* keyword, /* FITS keyword */ 203 short ival); /* short value */ 204 int hputi4( /* Implant int value into FITS header */ 205 char* hstring, /* FITS header string (modified) */ 206 const char* keyword, /* FITS keyword */ 207 const int ival); /* int value */ 208 int hputr4( /* Implant float value into FITS header */ 209 char* hstring, /* FITS header string (modified) */ 210 const char* keyword, /* FITS keyword */ 211 const float* rval); /* float (4 byte) value */ 212 int hputr8( /* Implant short into FITS header */ 213 char* hstring, /* FITS header string (modified) */ 214 const char* keyword, /* FITS keyword */ 215 const double dval); /* double value */ 216 int hputnr8( /* double with specified number of decimal places */ 217 char* hstring, /* FITS header string (modified) */ 218 const char* keyword, /* FITS keyword */ 219 const int ndec, /* Number of decimal places in keyword value */ 220 const double dval); /* double value */ 221 int hputs( /* Quoted character string into FITS header */ 222 char* hstring, /* FITS header string (modified) */ 223 const char* keyword, /* FITS keyword */ 224 const char* cval); /* Character string value */ 225 int hputm( /* Quoted character string, mutiple keywords */ 226 char* hstring, /* FITS header string (modified) */ 227 const char* keyword, /* FITS keyword */ 228 const char* cval); /* Character string value */ 229 int hputcom( /* Add comment to keyword line in FITS header */ 230 char* hstring, /* FITS header string (modified) */ 231 const char* keyword, /* FITS keyword */ 232 const char* comment); /* Comment string */ 233 int hputra( /* Right ascension in degrees into hh:mm:ss.sss */ 234 char* hstring, /* FITS header string (modified) */ 235 const char* keyword, /* FITS keyword */ 236 const double ra); /* Right ascension in degrees */ 237 int hputdec( /* Declination in degrees into dd:mm:ss.ss */ 238 char* hstring, /* FITS header string (modified) */ 239 const char* keyword, /* FITS keyword */ 240 const double dec); /* Declination in degrees */ 241 int hputl( /* Implant boolean value into FITS header */ 242 char* hstring, /* FITS header string (modified) */ 243 const char* keyword, /* FITS keyword */ 244 const int lval); /* 0->F, else ->T */ 245 int hputc( /* Implant character string without quotes */ 246 char* hstring, /* FITS header string (modified) */ 247 const char* keyword, /* FITS keyword */ 248 const char* cval); /* Character string value */ 249 250 int hdel( /* Delete a keyword line from a FITS header */ 251 char* hstring, /* FITS header string (modified) */ 252 const char* keyword); /* FITS keyword to delete */ 253 int hadd( /* Add a keyword line from a FITS header */ 254 char* hplace, /* Location in FITS header string (modified) */ 255 const char* keyword); /* FITS keyword to add */ 256 int hchange( /* Change a keyword name in a FITS header */ 257 char* hstring, /* FITS header string (modified) */ 258 const char* keyword1, /* Current FITS keyword name */ 259 const char* keyword2); /* New FITS keyword name */ 260 261 void ra2str( /* Convert degrees to hh:mm:ss.ss */ 262 char *string, /* Character string (returned) */ 263 int lstr, /* Length of string */ 264 const double ra, /* Right ascension in degrees */ 265 const int ndec); /* Number of decimal places in seconds */ 266 void dec2str( /* Convert degrees to dd:mm:ss.ss */ 267 char *string, /* Character string (returned) */ 268 int lstr, /* Length of string */ 269 const double dec, /* Declination in degrees */ 270 const int ndec); /* Number of decimal places in arcseconds */ 271 void deg2str( /* Format angle into decimal degrees string */ 272 char *string, /* Character string (returned) */ 273 int lstr, /* Length of string */ 274 const double deg, /* Angle in degrees */ 275 const int ndec); /* Number of decimal places in degrees */ 276 void num2str( /* Format number into string */ 277 char *string, /* Character string (returned) */ 278 const double num, /* Number */ 279 const int field, /* Total field size in characters */ 280 const int ndec); /* Number of decimal places */ 281 void setheadshrink( /* 0 to keep blank line when keyword deleted */ 282 const int hsh); /* 1 to shrink header by one line */ 283 void setleaveblank( /* 1 to keep blank line where keyword deleted */ 284 const int hsh); /* 0 to shrink header by one line */ 285 286 #else /* K&R prototypes */ 287 288 /* Subroutines in hget.c */ 289 290 /* Extract a value from a FITS header for given keyword */ 291 extern int hgeti4(); /* int (Multiple WCS) */ 292 extern int hgeti4c(); /* int */ 293 extern int hgeti2(); /* short */ 294 extern int hgetr4(); /* float */ 295 extern int hgetr8(); /* double */ 296 extern int hgetr8c(); /* double (Multiple WCS) */ 297 extern int hgetra(); /* Right ascension in degrees from string */ 298 extern int hgetdec(); /* Declination in degrees from string */ 299 extern int hgetdate(); /* Date in years from FITS date string */ 300 extern int hgetl(); /* T->1, F->0 from FITS logical entry */ 301 extern int hgets(); /* Previously allocated string */ 302 extern int hgetsc(); /* Previously allocated string (Multiple WCS) */ 303 extern int hgetm(); /* Previously allocated string from multiple keywords */ 304 extern char *hgetc(); /* Return pointer to string */ 305 extern int hgetndec(); /* Number of decimal places in keyword value */ 306 307 /* Subroutines to convert strings to RA and Dec in degrees */ 308 extern double str2ra(); 309 extern double str2dec(); 310 311 /* Check to see whether a string is a number or not */ 312 extern int isnum(); 313 extern int notnum(); 314 extern int decnum(); 315 316 /* Find given keyword entry in FITS header */ 317 extern char *ksearch(); 318 319 /* Find beginning of fillable blank line before FITS header keyword */ 320 extern char *blsearch(); 321 322 /* Search for substring s2 within string s1 */ 323 extern char *strsrch (); /* s1 null-terminated */ 324 extern char *strnsrch (); /* s1 ls1 characters long */ 325 extern char *strcsrch (); /* s1 null-terminated (case-insensitive) */ 326 extern char *strncsrch (); /* s1 ls1 characters long (case-insensitive) */ 327 extern void strfix(); /* Drop or change extraneous characters in string */ 328 329 /* Set length of header which is not null-terminated */ 330 extern int hlength(); 331 332 /* Get length of current FITS header */ 333 extern int gethlength(); 334 335 /* Subroutines in iget.c */ 336 extern int mgetstr(); /* Previously allocated string from multiline keyword */ 337 extern int mgetr8(); /* double from multiline keyword */ 338 extern int mgeti4(); /* int from multiline keyword */ 339 extern int igeti4(); /* long integer from IRAF compound keyword value */ 340 extern int igetr4(); /* real from IRAF compound keyword value */ 341 extern int igetr8(); /* double from IRAF compound keyword value */ 342 extern int igets(); /* character string from IRAF compound keyword value */ 343 extern char *igetc(); /* Extract string from IRAF keyword string */ 344 345 /* Subroutines in hput.c */ 346 347 /* Implant a value into a FITS header for given keyword */ 348 extern int hputi4(); /* int */ 349 extern int hputi2(); /* short */ 350 extern int hputr4(); /* float */ 351 extern int hputr8(); /* double */ 352 extern int hputnr8(); /* double with specified number of decimal places */ 353 extern int hputra(); /* Right ascension in degrees into hh:mm:ss.sss */ 354 extern int hputdec(); /* Declination in degrees into dd:mm:ss.ss */ 355 extern int hputl(); /* 0 -> F, else T FITS logical entry */ 356 extern int hputs(); /* Quoted character string */ 357 extern int hputm(); /* Quoted character string into mutiple keywords */ 358 extern int hputc(); /* Character string without quotes (returns 0 if OK) */ 359 extern int hputcom(); /* Comment after keyword=value (returns 0 if OK) */ 360 361 extern int hdel(); /* Delete a keyword line from a FITS header */ 362 extern int hadd(); /* Add a keyword line to a FITS header */ 363 extern int hchange(); /* Change a keyword name in a FITS header */ 364 extern void setheadshrink(); /* Set flag for deleted keyword space disposition*/ 365 extern void setleaveblank(); /* Set flag for deleted keyword space disposition*/ 366 367 /* Subroutines to convert RA and Dec in degrees to strings */ 368 extern void ra2str(); 369 extern void dec2str(); 370 371 extern void deg2str(); 372 extern void num2str(); 373 extern int numdec(); /* Return number of decimal places in number */ 374 375 extern char *getltime(); /* Return current local time in ISO format */ 376 extern char *getutime(); /* Return current UT as an ISO-format string */ 377 378 #endif /* __STDC__ */ 379 380 #ifdef __cplusplus 381 } 382 #endif /* __cplusplus */ 383 384 #endif /* fitshead_h_ */ 385 386 /* Apr 26 1996 Add HGETDATE to get year from date string 387 * May 22 1996 Return double from STR2RA and STR2DEC 388 * May 31 1996 Use stream I/O for reading as well as writing 389 * Jun 12 1996 Add byte-swapping subroutines 390 * Jul 10 1996 FITS header now allocated in subroutines 391 * Jul 17 1996 Add FITS table column extraction subroutines 392 * Jul 19 1996 Add declarations for header implanting subroutines 393 * Aug 5 1996 Add HLENGTH for FITS headers which are not null-terminated 394 * Aug 5 1996 Add STRNSRCH for FITS headers which are not null-terminated 395 * Aug 6 1996 Add HPUTNR8 to save a specified number of decimal places 396 * Aug 6 1996 Add MOVEPIX, HDEL and HCHANGE declarations 397 * Nov 1 1996 Add DEG2STR 398 * Dec 12 1996 Add ISNUM 399 * 400 * Oct 10 1997 FITS file opening subroutines now return int instead of FILE * 401 * 402 * Mar 12 1998 Add NOTNUM 403 * Apr 30 1998 Clean up declarations and add more comments 404 * May 12 1998 Add MGETS, MGETR8, MGETI4 for IRAF multi-line keywords 405 * May 26 1998 Add HGETNDEC for number of decimal places in keyword value 406 * May 27 1998 Add BLSEARCH to find usable blank lines in header 407 * May 27 1998 Split off fitsio and imhio subroutines to fitsio.h 408 * May 27 1998 Add all subroutines in hget.c, hput.c, and iget.c to C++ dec. 409 * Jun 24 1998 Add string lengths to ra2str(), dec2str, and deg2str() calls 410 * Jun 25 1998 Fix other C++ declarations with added string lengths 411 * Aug 31 1998 Add current date subroutines getltime() and getutime() 412 * Oct 28 1998 Add missing hgetc() to non c++ declarations 413 * 414 * Oct 6 1999 Add gethlength() to return current size of header 415 * Oct 14 1999 All HPUT subroutines now return an error code, 0 if OK, else -1 416 * Oct 15 1999 Add hputcom() declaration 417 * Oct 21 1999 Add hgetm() declaration 418 * 419 * Mar 22 2000 Add int to iget*() declarations 420 * Mar 27 2000 Add hputm() declaration 421 * 422 * Apr 3 2002 Add hgeti4c(), hgetr8c(), and hgetsc() 423 * Apr 8 2002 Include sys/types.h 424 * Aug 30 2002 Add strcsrch() and strncsrch() 425 * 426 * Sep 23 2003 Change mgets() to mgetstr() to avoid name collision at UCO Lick 427 * Oct 20 2003 Add numdec() to return the number of decimal places in a string 428 * 429 * Feb 26 2004 Add igetc(), formerly internal to iget.c 430 * Jul 1 2004 Add setheadshrink() for hdel() 431 * Aug 30 2004 Add numdec() to non-C++ declarations 432 * 433 * May 22 2006 Add setleaveblank() to leave blank line where keyword is deleted 434 * Jun 28 2006 Add strfix() to clean up characters in strings 435 * Nov 29 2006 Drop semicolon at end of C++ ifdef 436 * 437 * Jan 9 2007 Fix declarations so ANSI prototypes are not just for C++ 438 */ 439