bump release to 0.4, updated change log
Annotate for file docs/index.txt
2013-06-20 benjamin.fra 1 ==========================================
2013-06-21 benjamin.fra 2 Feller: EPICS support for logging to files
2013-06-20 benjamin.fra 3 ==========================================
18:27:06 ' 4
' 5 .. image:: epics-logo.png
' 6 :align: right
' 7
' 8 :Maintainer: Ben Franksen <benjamin.franksen@helmholtz-berlin.de>
' 9 :Bug Reports: tech-talk@aps.anl.gov
2013-06-21 benjamin.fra 10 :Stability: experimental
2013-06-20 benjamin.fra 11
2013-06-21 benjamin.fra 12 .. toctree::
12:49:30 ' 13 :hidden:
' 14
' 15 Home <self>
2013-06-21 benjamin.fra 16 ChangeLog
2013-06-21 benjamin.fra 17
2013-06-20 benjamin.fra 18 Welcome to the home page of the **feller** project.
18:27:06 ' 19
' 20 About
' 21 =====
' 22
2013-06-21 benjamin.fra 23 Feller is a simple support module for the *Experimental Physics and Industrial
19:32:27 ' 24 Control System* (`EPICS`_). It provides the possibility to log messages from any
' 25 subsystem (a C file, a library, an SNL program, whatever) to a specified file. It
' 26 uses the standard EPICS errlog facility in order not to disturb the normal
2013-06-20 benjamin.fra 27 processing, even if acessing the file is slow.
18:27:06 ' 28
' 29 Download
' 30 ========
' 31
' 32 Releases are available here:
' 33
' 34 http://www-csr.bessy.de/control/SoftDist/feller/releases/
' 35
' 36 ========= ===========================
2013-06-21 benjamin.fra 37 Version Change Log
2013-06-20 benjamin.fra 38 --------- ---------------------------
2013-06-21 benjamin.fra 39 `0.4`_ :ref:`Release 0.4`
2013-06-21 benjamin.fra 40 `0.3`_ :ref:`Release 0.3`
12:49:30 ' 41 `0.2`_ :ref:`Release 0.2`
' 42 `0.1`_ :ref:`Release 0.1`
2013-06-20 benjamin.fra 43 ========= ===========================
18:27:06 ' 44
' 45 Development snapshots are available under the name
' 46
2013-06-21 benjamin.fra 47 feller-snapshot-<date>.tar.gz
2013-06-20 benjamin.fra 48
18:27:06 ' 49 In the releases directory there is always a symbolic link to the
' 50 `latest snapshot`_.
' 51
' 52 .. _latest snapshot: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-snapshot-latest.tar.gz
2013-06-21 benjamin.fra 53 .. _0.4: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.4.tar.gz
2013-06-21 benjamin.fra 54 .. _0.3: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.3.tar.gz
12:49:30 ' 55 .. _0.2: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.2.tar.gz
2013-06-20 benjamin.fra 56 .. _0.1: http://www-csr.bessy.de/control/SoftDist/feller/releases/feller-0.1.tar.gz
18:27:06 ' 57
' 58 Install
' 59 =======
' 60
' 61 Follow the usual procedure for installing an EPICS support module.
' 62
' 63 API
' 64 ===
' 65
2013-06-21 benjamin.fra 66 There is one type and 3 functions, and a (convenience) macro. To use them, include
19:40:29 ' 67 "feller.h".
2013-06-21 benjamin.fra 68
12:49:30 ' 69 ::
2013-06-20 benjamin.fra 70
18:27:06 ' 71 struct feller;
' 72
2013-06-21 benjamin.fra 73 The (opaque) type of feller objects.
12:49:30 ' 74
' 75 ::
2013-06-20 benjamin.fra 76
18:27:06 ' 77 struct feller *fellerCreate(const char *filename);
2013-06-21 benjamin.fra 78
19:32:27 ' 79 Create a feller object. The argument is the name of the file you want your messages
' 80 to be logged to. The ``filename`` gets hashed and the hash is turned into a prefix
' 81 string stored inside the feller. Any message that starts with this prefix string is
' 82 considered to be intended for this feller. To prepend the prefix, use
' 83 ``fellerGetPrefix``, see below. This procedure also opens the file for appending.
' 84
' 85 If the file cannot be opened, ``fellerCreate`` returns ``NULL`` and issues an error
' 86 message.
' 87
' 88 If there already exists a feller with the same ``filename``, ``fellerCreate`` will
' 89 *not* create a new one; instead, it will return the existing feller and output a
' 90 warning message (since often this will not be intended). Such fellers are referred
' 91 to as "shared" in what follows.
2013-06-20 benjamin.fra 92
18:27:06 ' 93 ::
' 94
' 95 fellerDestroy(struct feller *this)
' 96
2013-06-21 benjamin.fra 97 Destroy a feller object. If the feller is not shared, the file gets closed, and the
19:32:27 ' 98 feller de-registers itself from the errlog system. If the feller is shared, then
' 99 only an internal reference counter is decremented.
' 100
' 101 This means in order to really destroy a feller and close the file, ``fellerDestroy``
' 102 has to be called as often as ``fellerCreate`` (for the same ``filename``).
2013-06-21 benjamin.fra 103
2013-06-20 benjamin.fra 104 ::
18:27:06 ' 105
2013-06-21 benjamin.fra 106 char *fellerGetPrefix(struct feller *this)
2013-06-20 benjamin.fra 107
2013-06-21 benjamin.fra 108 Return a (hopefully) unique (but short) string identifying the messages for this
19:32:27 ' 109 feller. You need to prepend all the messages intended for your feller with this
' 110 string. The prefix string itself will be removed from the message before it gets
' 111 written to the file.
2013-06-20 benjamin.fra 112
18:27:06 ' 113 ::
' 114
' 115 #define fellerPrintf(feller, format, args...)\
2013-06-21 benjamin.fra 116 errlogPrintfNoConsole("%s" format, fellerGetPrefix(feller), ## args)
2013-06-20 benjamin.fra 117
2013-06-21 benjamin.fra 118 To actually log a message, you can call any of the standard errlog functions. This
19:32:27 ' 119 macro is a convenience wrapper for the most common case when you do not want to
' 120 print the message to the console. You can of course define your own wrapper macros,
' 121 maybe calling other errlog print functions.
2013-06-20 benjamin.fra 122
2013-06-21 benjamin.fra 123 .. warning::
12:49:30 ' 124
' 125 This requires gcc, since it defines a macro with a variable number of
' 126 arguments.
2013-06-20 benjamin.fra 127
18:27:06 ' 128
' 129 Usage
' 130 =====
' 131
' 132 The basic pattern is::
' 133
' 134 struct feller *myFeller = fellerCreate("mylogfile.log");
' 135
' 136 /* as often as you like, do: */
' 137 fellerPrintf(myFeller, formatstring, args /*...*/);
' 138 /* ... */
' 139
' 140 fellerDestroy(myFeller);
' 141
' 142 The source tree contains a complete example top, including usage inside an SNL
' 143 program.
' 144
' 145 .. toctree::
' 146
' 147 .. :ref:`genindex`
' 148
' 149 .. _EPICS: http://www.aps.anl.gov/epics/