funlib(3)

💖 NAME 💖

Okay bestie, this is funlib(3) from SAORD Documentation — the manual page for FunLib — the Funtools Programming Interface. That's the whole Funtools library vibe, and we're gonna get you fluent, no cap.

---

✨ SYNOPSIS ✨

A description of the Funtools library. That's it, that's the synopsis, and honestly? Iconic.

---

🌸 DESCRIPTION 🌸

🦋 Introduction to the Funtools Programming Interface 🦋

To create a Funtools application, you need to include the funtools.h definitions file in your code:

#include <funtools.h>

Then you call Funtools subroutines and functions to access Funtools data. The most important routines are:

• FunOpen: open a Funtools file
• FunInfoGet: get info about an image or table
• FunImageGet: retrieve image data
• FunImageRowGet: retrieve image data by row
• FunImagePut: output image data
• FunImageRowPut: output image data by row
• FunColumnSelect: select columns in a table for access
• FunTableRowGet: retrieve rows from a table
• FunTableRowPut: output rows to a table
• FunClose: close a Funtools file

Your program must be linked against the libfuntools.a library, along with the math library. The following libraries also might be required on your system:

• -lsocket -lnsl for socket support
• -ldl for dynamic loading

For example, on a Solaris system using gcc, use the following link line:

gcc -o foo foo.c -lfuntools -lsocket -lnsl -ldl -lm

On a Solaris system using Solaris cc, use the following link line:

gcc -o foo foo.c -lfuntools -lsocket -lnsl -lm

On a Linux system using gcc, use the following link line:

gcc -o foo foo.c -lfuntools -ldl -lm

Once configure has built a Makefile on your platform, the required "extra" libraries (aside from -lm, which always is required) are specified in that file's EXTRA_LIBS variable. For example, under Linux you will find:

grep EXTRA_LIBS Makefile
EXTRA_LIBS      =  -ldl
...

The Funtools library contains both the zlib library (http://www.gzip.org/zlib/) and Doug Mink's WCS library (http://tdc-www.harvard.edu/software/wcstools/). It is not necessary to put these libraries on a Funtools link line. Include files necessary for using these libraries are installed in the Funtools include directory.

🧚 Funtools Programming Tutorial 🧚

The FunOpen() function is used to open a FITS file, an array, or a raw event file:

/* open the input FITS file for reading */
ifun = FunOpen(iname, "r", NULL);
/* open the output FITS file for writing, and connect it to the input file */
ofun = FunOpen(iname, "w", ifun);

A new output file can inherit header parameters automatically from existing input file by passing the input Funtools handle as the last argument to the new file's FunOpen() call as shown above.

For image data, you then can call FunImageGet() to read an image into memory.

float buf=NULL;
/* extract and bin the data section into an image buffer */
buf = FunImageGet(fun, NULL, "bitpix=-32");

If the (second) buf argument to this call is NULL, buffer space is allocated automatically. The (third) plist argument can be used to specify the return data type of the array. If NULL is specified, the data type of the input file is used.

To process an image buffer, you would generally make a call to FunInfoGet() to determine the dimensions of the image (which may have been changed from the original file dimensions due to Funtools image sectioning on the command line). In a FITS image, the index along the dim1 axis varies most rapidly, followed by the dim2 axis, etc. Thus, to access each pixel in an 2D image, use a double loop such as:

buf = FunImageGet(fun, NULL, "bitpix=-32");
FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
for(i=1; i<=dim2; i++){
  for(j=1; j<=dim1; j++){
    ... process buf[((i-1)*dim1)+(j-1)] ...
  }
}

or:

buf = FunImageGet(fun, NULL, "bitpix=-32");
FunInfoGet(fun, FUN_SECT_DIM1, &dim1, FUN_SECT_DIM2, &dim2, 0);
for(i=0; i<(dim1*dim2); i++){
  ... process buf[i] ...
}

Finally, you can write the resulting image to disk using FunImagePut():

FunImagePut(fun2, buf, dim1, dim2, -32, NULL);

Note that Funtools automatically takes care of book-keeping tasks such as reading and writing FITS headers (although you can, of course, write your own header or add your own parameters to a header).

For binary tables and raw event files, a call to FunOpen() will be followed by a call to the FunColumnSelect() routine to select columns to be read from the input file and/or written to the output file:

typedef struct evstruct{
  double time;
  int time2;
} *Ev, EvRec;
FunColumnSelect(fun, sizeof(EvRec), NULL,
                "time",      "D",     "rw",  FUN_OFFSET(Ev, time),
                "time2",     "J",     "w",   FUN_OFFSET(Ev, time2),
                NULL);

Columns whose (third) mode argument contains an "r" are "readable", i.e., columns will be read from the input file and converted into the data type specified in the call's second argument. These columns values then are stored in the specified offset of the user record structure. Columns whose mode argument contains a "w" are "writable", i.e., these values will be written to the output file. The FunColumnSelect() routine also offers the option of automatically merging user columns with the original input columns when writing the output rows.

Once a set of columns has been specified, you can retrieve rows using FunTableRowGet(), and write the rows using FunTableRowPut():

Ev ebuf, ev;
/* get rows -- let routine allocate the array */
while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
  /* process all rows */
  for(i=0; i<got; i++){
    /* point to the i'th row */
    ev = ebuf+i;
    /* time2 is generated here */
    ev->time2 = (int)(ev->time+.5);
    /* change the input time as well */
    ev->time = -(ev->time/10.0);
  }
  /* write out this batch of rows with the new column */
  FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL);
  /* free row data */
  if( ebuf ) free(ebuf);
}

The input rows are retrieved into an array of user structs, which can be accessed serially as shown above. Once again, Funtools automatically takes care of book-keeping tasks such as reading and writing FITS headers (although you can, of course, write your own header or add your own parameters to a header).

When all processing is done, you can call FunClose() to close the file(s):

FunClose(fun2);
FunClose(fun);

These are the basics of processing FITS files (and arrays or raw event data) using Funtools. The routines in these examples are described in more detail below, along with a few other routines that support parameter access, data flushing, etc.

🎀 Compiling and Linking 🎀

To create a Funtools application, a software developer will include the funtools.h definitions file in Funtools code:

#include <funtools.h>

The program is linked against the libfuntools.a library, along with the math library (and the dynamic load library, if the latter is available on your system):

gcc -o foo foo.c -lfuntools -ldl -lm

If gcc is used, Funtools filtering can be performed using dynamically loaded shared objects that are built at run-time. Otherwise, filtering is performed using a slave process.

Funtools has been built on the following systems:

• Sun/Solaris 5.X
• Linux/RedHat Linux 5.X,6.X,7.X
• Dec Alpha/OSF1 V4.X
• WindowsNT/Cygwin 1.0
• SGI/IRIX64 6.5

🌈 A Short Digression on Subroutine Order 🌈

There is a natural order for all I/O access libraries. You would not think of reading a file without first opening it, or writing a file after closing it. A large part of the experiment in funtools is to use the idea of "natural order" as a means of making programming easier. We do this by maintaining the state of processing for a given funtools file, so that we can do things like write headers and flush extension padding at the right time, without you having to do it.

For example, if you open a new funtools file for writing using FunOpen(), then generate an array of image data and call FunImagePut(), funtools knows to write the image header automatically. There is no need to think about writing a standard header. Of course, you can add parameters to the file first by calling one of the FunParamPut() routines, and these parameters will automatically be added to the header when it is written out. There still is no need to write the header explicitly.

Maintaining state in this way means that there are certain rules of order which should be maintained in any funtools program. In particular, we strongly recommend the following ordering rules be adhered to:

• When specifying that input extensions be copied to an output file via a reference handle, open the output file before reading the input file. (Otherwise the initial copy will not occur).
• Always write parameters to an output file using one of the FunParamPut() calls before writing any data. (This is a good idea for all FITS libraries, to avoid having to recopy data is the FITS header needs to be extended by adding a single parameter.)
• If you retrieve an image, and need to know the data type, use the FUN_SECT_BITPIX option of FunInfoGet(), after calling FunImageGet(), since it is possible to change the value of BITPIX from the latter.
• When specifying that input extensions be copied to an output file via a reference handle, close the output file before closing input file, or else use FunFlush() explicitly on the output file before closing the input file. (Otherwise the final copy will not occur).

We believe that these are the natural rules that are implied in most FITS programming tasks. However, we recognize that making explicit use of "natural order" to decide what automatic action to take on behalf of the programmer is experimental. Therefore, if you find that your needs are not compatible with our preferred order, please let us know -- it will be most illuminating for us as we evaluate this experiment.

🦋 Funtools Programming Examples 🦋

The following complete coding examples are provided to illustrate the simplicity of Funtools applications. They can be found in the funtest subdirectory of the Funtools distribution. In many cases, you should be able to modify one of these programs to generate your own Funtools program:

• evread.c: read and write binary tables
• evcols.c: add column and rows to binary tables
• evmerge.c: merge new columns with existing columns
• evnext.c: manipulate raw data pointers
• imblank.c: blank out image values below a threshold
• asc2fits.c — convert a specific ASCII table to FITS binary table

and that's the list, bestie 🎀 every single one of those little programs is out here doing its own lil job and honestly? iconic behaviour.

---

✨ The Funtools Programming Reference Manual ✨

okay so this is the part where we get into the actual C API, and it's giving very much "open your editor, we're doing this" 💅 the header you're pulling in is:

#include <funtools.h>

and here's every single prototype, verbatim, no cap, exactly as you should be calling them — do not freestyle these signatures, copy them character for character like the good student you are 🫶

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

void *FunImageGet(Fun fun, void *buf, char *plist)

int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix, char *plist)

void * FunImageRowGet(Fun fun, void *buf, int rstart, int rstop, char *plist)

void * FunImageRowPut(Fun fun, void *buf, int rstart, int rstop, int dim1, int dim2, int bitpix, char *plist)

int FunColumnSelect(Fun fun, int size, char *plist, ...)

void FunColumnActivate(Fun fun, char *s, char *plist)

int FunColumnLookup(Fun fun, char *s, int which, char **name, int *type, int *mode, int *offset, int *n, int *width)

void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, int *nrow)

int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist)

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)

int FunParamPutb(Fun fun, char *name, int n, int value, char *comm, int append)

int FunParamPuti(Fun fun, char *name, int n, int value, char *comm, int append)

int FunParamPutd(Fun fun, char *name, int n, double value, int prec, char *comm, int append)

int FunParamPuts(Fun fun, char *name, int n, char *value, char *comm, int append)

int FunInfoGet(Fun fun, int type, ...)

int FunInfoPut(Fun fun, int type, ...)

void FunFlush(Fun fun, char *plist)

void FunClose(Fun fun)

little heads up, bestie: the ... in FunColumnSelect and in FunInfoGet / FunInfoPut is a real variadic ellipsis, not me being lazy and trailing off mid-sentence 😭 it's in the signature, it stays in the signature.

---

🌈 SEE ALSO 🌈

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

go read the help pages, they're the group chat archive for all of this 💜

---

okay that's the whole page!! you ate that 🍓 this was version 1.4.5, dated April 14, 2011, and it's a funlib(3) moment — go forth and write some extremely correct code, mwah 💋✨