funparamget(3)

💖 funparamget — the manual page, bestie edition 💖

okay so you found the funparamget page, from the SAORD Documentation set — it lives in section 3 (that's your library-call girlies 💅). Sit down, grab a boba, and let's get into it, because this one is literally just "how do I read a value out of a FITS header" and it ATE.

---

✨ NAME ✨

FunParamGet — get a Funtools param value 🎀

---

🌸 SYNOPSIS 🌸

#include <funtools.h>

int FunParamGetb(Fun fun, char *name, int n, int defval, int *got)

int FunParamGeti(Fun fun, char *name, int n, int defval, int *got)

double FunParamGetd(Fun fun, char *name, int n, double defval, int *got)

char *FunParamGets(Fun fun, char *name, int n, char *defval, int *got)

---

🦋 DESCRIPTION 🦋

So there's four routines here — FunParamGetb(), FunParamGeti(), FunParamGetd(), and FunParamGets() — and they hand you back the value of a FITS header parameter as a boolean, an int, a double, and a string, respectively. Periodt. 💅

⚠️ and bestie, listen: the string that FunParamGets() gives you is a malloc'ed copy of the header value. You gotta free() it when you're done. Not optional. Not later. It's giving memory leak if you ghost it. 😭

🫶 the first argument

The first argument is the Fun handle associated with the FITS header you're poking at. Normally, that header is the one attached to the FITS extension you opened with FunOpen(). BUT — plot twist — you can use FunInfoPut() to say "actually, give me the primary header." Specifically: if you set the FUN_PRIMARYHEADER parameter to 1, then the primary header gets used for all parameter access until you reset that value back to 0. Like so:

int val;
FunParamGeti(fun, "NAXIS", 1, 0, &got);              # current header
val=1;
FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0);         # switch to ...
FunParamGeti(fun, "NAXIS", 1, 0, &got);              # ... primary header
FunParamGeti(fun, "NAXIS", 2, 0, &got);              # ... primary header
val=0;
FunInfoPut(fun, FUN_PRIMARYHEADER, &val, 0);         # switch back to ...
FunParamGeti(fun, "NAXIS", 2, 0, &got);              # current header

🌈 the other way (per-parameter)

Alternatively, you can use the FUN_PRIMARY macro to grab parameters from the primary header on a per-parameter basis:

FunParamGeti(fun, "NAXIS1", 0, 0, &got);              # current header
FunParamGeti(FUN_PRIMARY(fun), "NAXIS1", 0, 0, &got); # primary header

💀 NB — FUN_PRIMARY is deprecated. It uses a global parameter, so it will not be appropriate for threaded applications when funtools is made thread-safe. We recommend using FunInfoPut() to switch between the extension header and the primary header instead. (lowkey the glow-down of this whole page, ngl.)

For output data, access to the primary header is only possible until the header is written out — which usually happens when the first data are written. So like… get in before the door closes. 🚪✨

🎀 the second argument

The second argument is the name of the parameter you wanna access.

🧚 the third argument

The third argument, n — if it's non-zero — is an integer that gets added as a suffix to the parameter name. Which makes it stupid easy to loop through parameters that share a root name. For example, to gather up all values of TLMIN and TLMAX for each column in a binary table, you'd do:

for(i=0, got=1; got; i++){
  fun->cols[i]->tlmin = (int)FunParamGeti(fun, "TLMIN", i+1, 0.0, &got);
  fun->cols[i]->tlmax = (int)FunParamGeti(fun, "TLMAX", i+1, 0.0, &got);
}

🍓 the fourth argument (and the fifth!)

The fourth argument, defval, is the default value to return if the parameter doesn't exist. Heads up: the data type of this parameter is different for each specific FunParamGet() call — so don't go mixing them up. 👀

The final argument, got, will be 0 if no param was found. Otherwise, the data type of the parameter comes back like this:

• FUN_PAR_UNKNOWN ('u')
• FUN_PAR_COMMENT ('c')
• FUN_PAR_LOGICAL ('l')
• FUN_PAR_INTEGER ('i')
• FUN_PAR_STRING ('s')
• FUN_PAR_REAL ('r')
• FUN_PAR_COMPLEX ('x')

💜 what they return

These routines return the value of the header parameter, or the specified default value if the header parameter doesn't exist. And again, bestie, because it bears repeating: the returned value is a malloc'ed string and should be freed when no longer needed. 🫶

🌟 raw cards, the main character energy

By default, FunParamGets() returns the string value of the named parameter. However — you can use FunInfoPut() to get the raw 80-character FITS card instead. Specifically: if you set the FUN_RAWPARAM parameter to 1, then card images will be returned by FunParamGets() until you reset that value to 0.

Alternatively, if the FUN_RAW macro is applied to the name, then the 80-character raw FITS card is returned instead.

💀 NB — FUN_RAW is deprecated. It uses a global parameter, so it will not be appropriate for threaded applications when funtools is made thread-safe. We recommend using FunInfoPut() to switch between the extension header and the primary header.

🌸 the NULL-name trick (iykyk)

Note that on top of everything above, FunParamGets() will return the 80 raw characters of the *n*th FITS card (including the comment) if name is specified as NULL and n is positive. For example, to loop through all FITS header cards in a given extension and print out the raw card, use:

for(i=1; ;i++){
  if( (s = FunParamGets(fun, NULL, i, NULL, &got)) ){
    fprintf(stdout, "%.80s\n", s);
    free(s);
  }
  else{
    break;
  }
}

---

👑 SEE ALSO 👑

See funtools(7) for a list of Funtools help pages.

---

and that's the whole page, babe — you're officially a header-reading icon 🎀✨

signing off from version 1.4.5, dated April 14, 2011, on the funparamget(3) page 🦋💖 stay slay, free your strings, and never use the deprecated macros fr fr 💅