funopen(3)

💖 funopen — open a Funtools data file 💖

okay bestie, gather round, because this is the function that opens the door to literally everything in Funtools 🚪✨ (the manual page header says funopen(3) from SAORD Documentation, but we're not doing boring title lines today, we're doing vibes)

---

✨ SYNOPSIS ✨

#include <funtools.h>

Fun FunOpen(char *name, char *mode, Fun ref);

---

🌸 DESCRIPTION 🌸

So FunOpen() is the main character here 👑 — it opens a Funtools data file for reading or appending, or it creates a whole new FITS file for writing. The name argument is literally just the name of the Funtools data file you wanna open. And yes, you can absolutely use IRAF-style bracket notation to specify Funtools Files, Extensions, and Filters 🎀 (iykyk).

ngl, you have to make a separate call every single time you access a different FITS extension. no shortcuts, no cheating:

Fun fun;
char *iname;
...
if( !(fun = FunOpen(iname, "r", NULL)) ){
  fprintf(stderr, "could not FunOpen input file: %s\n", iname);
  exit(1);
}

If mode is "r", the file gets opened for reading, and processing is all set up to begin at the specified extension 💅 For reading, name can be stdin, in which case standard input is what gets read.

If mode is "w", the file is created if it doesn't exist yet, or opened and truncated for writing if it does exist 😭 Processing starts at the beginning of the file. The name can be stdout, in which case standard output is readied for processing.

If mode is "a", the file is created if it does not exist, or opened if it does exist. Processing starts at the end of the file. The name can be stdout, in which case standard output is readied for processing.

---

🦋 the reference handle era 🦋

When a Funtools file is opened for writing or appending, a previously opened Funtools reference handle can be passed in as that third argument. That handle is typically associated with the input Funtools file that'll be used to generate the data for the output data. And when you specify a reference file like this, the output file inherits the (extension) header parameters from the input file 🧚✨:

Fun fun, fun2;
...
/* open input file */
if( !(fun = FunOpen(argv[1], "r", NULL)) )
  gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
/* open the output FITS image, inheriting params from input */
if( !(fun2 = FunOpen(argv[2], "w", fun)) )
  gerror(stderr, "could not FunOpen output file: %s\n", argv[2]);

So in that example above, the output FITS binary table file inherits all the parameters associated with the input binary table extension. periodt 💅

A file opened for writing with a Funtools reference handle also inherits the selected columns — as in, those columns chosen for processing using the FunColumnSelect() routine — from the reference file, and those become its default columns 🌈 This makes it super easy to open an output file so that the columns written to the output are the same as the columns read in from the input. Obsessed. Of course, column selection can easily be tailored using the FunColumnSelect() routine. In particular, it's easy to merge user-defined columns with the input columns to generate a new file 🔥 See the evmerge for a complete example.

---

🎀 copying all the other extensions 🎀

In addition, when a Funtools reference handle is supplied in a FunOpen() call, you can also specify that all other extensions from the reference file (other than the input extension being processed) should be copied from the reference file to the output file 💖 This is useful, for example, when you're processing a FITS binary table or image and you want all of the other extensions copied to the output file too. Copy of other extensions is controlled by adding a "C" or "c" to the mode string of the FunOpen() call of the input reference file.

• If "C" is specified, then other extensions are always copied (i.e., copy is forced by the application).
• If "c" is used, then other extensions are copied if the user requests copying by adding a plus sign "+" to the extension name in the bracket specification.

For example, the funtable program utilizes "c" mode, giving users the option of copying all other extensions:

/* open input file -- allow user copy of other extensions */
if( !(fun = FunOpen(argv[1], "rc", NULL)) )
  gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
/* open the output FITS image, inheriting params from input */
if( !(fun2 = FunOpen(argv[2], "w", fun)) )
  gerror(stderr, "could not FunOpen output file: %s\n", argv[2]);

So funtable supports either of these command lines, slay:

# copy only the EVENTS extension
csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev
# copy ALL extensions
csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev

---

⚠️ the tea you actually need to know ⚠️

Use of a Funtools reference handle implies that the input file is opened before the output file. However — and this is important, bestie, do not skip this part 🙈 — if copy mode ("c" or "C") is specified for the input file, the actual input file open is delayed until just after the output file is opened, since the copy of prior extensions to the output file takes place while Funtools is seeking to the specified input extension.

This implies that the output file should be opened before any I/O is done on the input file or else the copy will fail 💀

Note also that the copy of subsequent extension will be handled automatically by FunClose() if the output file is closed before the input file. Alternatively, it can be done explicitly by FunFlush(), but again, this assumes that the input file still is open.

---

🌟 return values 🌟

Upon success, FunOpen() returns a Fun handle that's used in subsequent Funtools calls 💜 On error, NULL is returned. that's it, that's the whole vibe check.

---

👀 SEE ALSO 👀

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

---

and that's a wrap, bestie 🫶 this lil page was version 1.4.5, dated April 14, 2011 — yeah she's vintage but she still ate 💅✨ bye ily, go open some files 🍓