You can also browse emlog's CVS Repository, or access emlog using CVS tools using the instructions found here (module name is misc/emlog).
The emlog kernel module implements simple character device driver. The driver acts like a named pipe that has a finite, circular buffer. The size of the buffer is easily configurable. As more data is written into the buffer, the oldest data is discarded. A process that reads from an emlog device will first read the existing buffer, then see new text as it's written, similar to monitoring a log file using "tail -f". (Non-blocking reads are also supported, if a process needs to get the current contents of the log without blocking to wait for new data.)
The current version of emlog should work under just about any Linux kernel in the 2.x series, including 2.4.
emlog is free software, distributed under the GNU General Public License (GPL); see the file COPYING (in the distribution) for details.
First, decide which major number you would like to use for emlog. This is configured in emlog.h using the constant EMLOG_MAJOR_NUMBER. The default is 241, which is in the "local/experimental use" range according to the kernel documentation (similar to the 10/8 or 192.168/16 IP networks). Setting the major number to 0 will cause the kernel to dynamically assign a major number to emlog.
Next, if your kernel source tree is not rooted in the default directory of /usr/src/linux, modify the Makefile constant KERNEL_HOME to reflect its actual location.
After configuration, compile by typing 'make'. Two files should be generated: the kernel module itself (emlog.o), and the nbcat utility that will be described later.
Finally, insert the module into the kernel using the 'insmod' command; e.g. 'insmod emlog.o'. If successful, a message similar to "emlog: version 0.40 running, using major number 241" should show up in your kernel log (type 'dmesg' or 'cat /proc/kmsg' to see it). You can also verify that the module has been inserted by typing 'cat /proc/modules'.
Next, you must use 'mknod' to create device files that your processes can write to. The major number of the device files should be whatever number you selected in Step 1 (e.g., 241). The minor number is used to indicate the size of the ring buffer for that device file, specified as the the number of kilobytes (e.g., 1024 bytes). For example, to create an 8K buffer called 'testlog':
% mknod /tmp/testlog c 241 8You can create as many devices as you like. Internally, emlog uses the file's inode and device numbers to identify the buffer to which the file refers.
Once the device file has been created, simply write to your device file as you would any normal named pipe, e.g.
% echo hello > /tmp/testlogWrites to the log will never block because the buffer never runs out of space; old data is simply overwritten by new data. You can read from the log in the normal way, e.g. using cat. By default, reads block, just like "tail -f", waiting for new log data. For example:
% cat /tmp/testlog hello [we immediately see the hello that we wrote in the previous step] _ [... and here's the cursor. the 'cat' process is now blocked, waiting for new input. New data will be displayed as it is written to the device by other processes.] ^C [use control-c, for example, to stop reading.]As of version 0.40, emlog's buffers can be read and/or monitored by multiple concurrent readers correctly. Data written to an emlog device will not disappear until it is overwritten by newer data, or the emlog module is removed. (In versions 0.30 and earlier, data was removed from the buffer the first time it was read.)
Type 'rmmod emlog' will remove the emlog kernel module and free all associated buffers. This won't work until all emlog device files are closed.
In other words, buffers are persistent, even after a process closes the emlog device. Therefore, it is possible (naturally) to fill virtual memory by creating many large emlog devices and writing one byte to all of them. Don't do that. All buffers will be freed when the emlog kernel module is removed.
nbcat /var/log/emlog-device-instance > /tmp/saved-log-file...will copy the current contents of the named emlog device to a file in /tmp.
Q: When I try to compile emlog, I get hundreds of errors related
to header files.
A: If your kernel sources are rooted anywhere other than
/usr/src/linux, make sure you change the KERNEL_HOME variable in the
Makefile to reflect their location. If you've recently installed new
kernel sources, make sure that you've run "make config" or "make
menuconfig" in the kernel's root (e.g. /usr/src/linux). You don't
actually have to go through the entire configuration; just make sure
that you have a /usr/include/asm and a /usr/include/linux that are
symbolic links into your kernel source tree.
Q: When I try to insert the module using 'insmod', I get 'I/O error'.
A: That usually means the major device number being registered by
emlog is already in use by another device driver. Type 'cat
/proc/devices' to see a list of major device numbers that are in use.
If there is a collision, edit emlog.h and change emlog's major device
number to an unused number (or, change it to 0 in order to get a
dynamically assigned major number).
Q: I'm seeing "I/O error" at a time other then when the module is
inserted.
A: Oops - you've found a bug in emlog. Please report it.
Q: When I try to access an emlog device file for reading or writing,
I get the error "no such device".
A: This probably means either that the emlog kernel module is not
loaded; or, that the major number of the device file does not match
the major number that emlog registered. To see which major number is
being used by emlog, type 'cat /proc/devices | grep emlog'.
Q: When I try to access an emlog device file for reading or writing,
I get the error "invalid argument".
A: The minor number of the emlog device file must be a number
between 1 and 128, representing the number of kilobytes (1,024 bytes)
that should be used for emlog's ring buffer. Make sure you're
specifying a valid minor number in your 'mknod' statement. Don't use 0.
Q: I see "no memory" errors when I try opening new emlog files.
A: Looks like you're out of virtual memory, sport.
Q: When I try to remove the emlog driver ("rmmod emlog"), I get the
error "Device or resource busy".
A: A process is currently using an emlog device. You have to wait
until all processes close all emlog device files until the driver can
be removed. Try using "lsof" to see which files are in use by which
processes.
Q: I am trying to save a copy of the current emlog buffer to another
file, by typing "cp /tmp/emlog-test /tmp/saved-log-copy", but cp just
sits there forever.
A: cp is blocked waiting for more data, just like 'cat' does when
used with an emlog device. Use 'nbcat', the non-blocking cat utility
included with the emlog distribution; for example: 'nbcat /tmp/emlog-test >
/tmp/saved-log-copy'
Q: You've made my computer crash.
A: Sorry. If you can reproduce the problem I'll try to fix it.
Bug reports, patches, complaints, praise, and submissions of Central Services Form 27B/6, are welcomed by the author, Jeremy Elson (jelson@circlemud.org).
Emlog was written by Jeremy Elson (jelson@circlemud.org) at the USC's Information Sciences Institute, as part of the SCADDS project. SCADDS is an embedded systems research project. We use small PC/104-bus-based single-board-PCs using Linux. We wanted to save the debugging output from certain processes, but since these things have 16MB of disk space and 32MB of RAM, keeping complete log files was not an option. These tiny nodes do have serial ports running PPP, though, so it's possible to walk over to a node with a laptop, plug in a serial cable, and then telnet into the box. Using emlog, we can always keep the most recent debug messages from our processes; in case of an error, we can plug in a debug console and see what went wrong.
This work was supported by DARPA under grant No. DABT63-99-1-0011 as part of the SCADDS project, and was also made possible in part due to support from Cisco Systems.
Last updated: 8 March 2002
Back to my software page
Back to my home page
Jeremy Elson