Feller: EPICS support for logging to files

_images/epics-logo.png
Maintainer:Ben Franksen <benjamin.franksen@helmholtz-berlin.de>
Bug Reports:tech-talk@aps.anl.gov
Stability:experimental

Welcome to the home page of the feller project.

About

Feller is a simple support module for the Experimental Physics and Industrial Control System (EPICS). It provides the possibility to log messages from any subsystem (a C file, a library, an SNL program, whatever) to a specified file. It uses the standard EPICS errlog facility in order not to disturb the normal processing, even if accessing the file is slow.

Download

Releases are available here:

Development snapshots are available under the name

feller-snapshot-<date>.tar.gz

In the releases directory there is always a symbolic link to the latest snapshot.

Install

Follow the usual procedure for installing an EPICS support module.

API

There is one type and 3 functions, and a (convenience) macro. To use them, include “feller.h”.

struct feller;

The (opaque) type of feller objects.

struct feller *fellerCreate(const char *filename);

Create a feller object. The argument is the name of the file you want your messages to be logged to. The filename gets hashed and the hash is turned into a prefix string stored inside the feller. Any message that starts with this prefix string is considered to be intended for this feller. To prepend the prefix, use fellerGetPrefix, see below. This procedure also opens the file for appending.

If the file cannot be opened, fellerCreate returns NULL and issues an error message.

If there already exists a feller with the same filename, fellerCreate will not create a new one; instead, it will return the existing feller and output a warning message (since often this will not be intended). Such fellers are referred to as “shared” in what follows.

fellerDestroy(struct feller *this)

Destroy a feller object. If the feller is not shared, the file gets closed, and the feller de-registers itself from the errlog system. If the feller is shared, then only an internal reference counter is decremented.

This means in order to really destroy a feller and close the file, fellerDestroy has to be called as often as fellerCreate (for the same filename).

char *fellerGetPrefix(struct feller *this)

Return a (hopefully) unique (but short) string identifying the messages for this feller. You need to prepend all the messages intended for your feller with this string. The prefix string itself will be removed from the message before it gets written to the file.

#define fellerPrintf(feller, format, args...)\
 errlogPrintfNoConsole("%s" format, fellerGetPrefix(feller), ## args)

To actually log a message, you can call any of the standard errlog functions. This macro is a convenience wrapper for the most common case when you do not want to print the message to the console. You can of course define your own wrapper macros, maybe calling other errlog print functions.

Warning

This requires gcc, since it defines a macro with a variable number of arguments.

Usage

The basic pattern is:

struct feller *myFeller = fellerCreate("mylogfile.log");

/* as often as you like, do: */
fellerPrintf(myFeller, formatstring, args /*...*/);
/* ... */

fellerDestroy(myFeller);

The source tree contains a complete example top, including usage inside an SNL program.

Table Of Contents

Next topic

Change Log