|
version 1.15, 2001/08/13 21:12:47
|
version 1.16, 2001/08/13 23:19:40
|
|
|
|
| written into the buffer, the oldest data is discarded. A process that | written into the buffer, the oldest data is discarded. A process that |
| reads from an emlog device will first read the existing buffer, then | 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 | see new text as it's written, similar to monitoring a log file using |
| "tail -f". |
"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.) |
| | |
| Version 0.30 of emlog (released March 1, 2001) should work under just |
The current version of emlog should work under just about any Linux |
| about any Linux kernel in the 2.x series, including 2.4. |
kernel in the 2.x series, including 2.4. |
| | |
| emlog is free software, distributed under the GNU General Public | emlog is free software, distributed under the GNU General Public |
| License (GPL); see the file COPYING for details. |
License (GPL); see the file COPYING (in the distribution) for details. |
| | |
| | |
| How is emlog used? | How is emlog used? |
|
|
|
| Setting the major number to 0 will cause the kernel to dynamically | Setting the major number to 0 will cause the kernel to dynamically |
| assign a major number to emlog. | assign a major number to emlog. |
| | |
| Next, compile using the Makefile provided. Typing 'make' should |
Next, if your kernel source tree is not rooted in the default |
| generate a single object file, 'emlog.o'. Insert the module into |
directory of /usr/src/linux, modify the Makefile constant |
| the kernel using the 'insmod' command; e.g. 'insmod emlog.o'. |
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'. |
| |
|
| | |
| 2: Create device files for emlog | 2: Create device files for emlog |
| | |
| Next, you must use 'mknod' to create device files that your | Next, you must use 'mknod' to create device files that your |
| processes can write to. The major number of the device files | processes can write to. The major number of the device files |
| should be whatever number you selected in Step 1 (e.g., 241). The | 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 |
minor number is used to indicate the *size* of the ring |
| that device file, specified as the the number of kilobytes (e.g., |
buffer for that device file, specified as the the number of |
| 1024 bytes). For example, to create an 8K buffer called 'testlog': |
kilobytes (e.g., 1024 bytes). For example, to create an 8K buffer |
| |
called 'testlog': |
| | |
| % mknod /tmp/testlog c 241 8 | % mknod /tmp/testlog c 241 8 |
| | |
| You can create as many devices as you like. Internally, emlog uses | You can create as many devices as you like. Internally, emlog uses |
| the file's inode number to identify which buffer it refers to. |
the file's inode and device numbers to identify the buffer to which |
| |
the file refers. |
| | |
| 3: Write to and read from your new device file |
|
| | |
| |
3: Write to and read from your new device file |
| Once the device file has been created, simply write to your device | Once the device file has been created, simply write to your device |
| file as you would any normal named pipe, e.g. | file as you would any normal named pipe, e.g. |
| | |
| % echo hello > /tmp/testlog | % echo hello > /tmp/testlog |
| | |
| Writes will never block because the buffer never runs out of space; |
Writes to the log will never block because the buffer never runs |
| old data is simply overwritten by new data. |
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. Note |
You can read from the log in the normal way, e.g. using cat. By |
| that reads block, just like "tail -f", waiting for new log data. |
default, reads block, just like "tail -f", waiting for new log |
| For example: |
data. For example: |
| | |
| % cat /tmp/testlog | % cat /tmp/testlog |
| hello [we immediately see the hello that we wrote in the previous step] | hello [we immediately see the hello that we wrote in the previous step] |
|
|
|
| as it is written to the device by other processes.] | as it is written to the device by other processes.] |
| ^C [use control-c, for example, to stop reading.] | ^C [use control-c, for example, to stop reading.] |
| | |
| Note that the first process to consume data from an emlog buffer |
As of version 0.40, emlog's buffers can be read and/or monitored |
| will remove that text from the buffer. This differs from, say, |
by multiple concurrent readers correctly. Data written to an |
| the behavior of the 'dmesg' buffer, which may be read many times |
emlog device will not disappear until it is overwritten by newer |
| until it scrolls off. |
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.) |
| |
|
| | |
| 4: Remove emlog when you're done | 4: Remove emlog when you're done |
| | |
|
|
|
| are closed. | are closed. |
| | |
| | |
| |
|
| Other Usage Notes | Other Usage Notes |
| ================= | ================= |
| | |
| emlog will allocate a fixed-size buffer on behalf of a device file if |
* emlog will allocate a fixed-size buffer on behalf of a device file |
| one of the following two conditions is true: |
if one of the following two conditions is true: |
| | |
| 1- A process has the file open for reading or writing | 1- A process has the file open for reading or writing |
| 2- A process has written text to the pipe that has not been read |
2- A process has written text to the pipe |
| | |
| In other words, buffers are persistent, even after a process closes | In other words, buffers are persistent, even after a process closes |
| the pipe. If another process later reads the pipe, the text will |
the emlog device. Therefore, it is possible (naturally) to fill |
| still be there. Note that it is possible (naturally) to fill virtual |
virtual memory by creating many large emlog devices and writing one |
| memory by creating many such pipes, writing to all of them, and never |
byte to all of them. Don't do that. All buffers will be freed when |
| reading the data out of them. All buffers will be freed when the |
the emlog kernel module is removed. |
| emlog kernel module is removed. |
|
| | |
| Non-blocking reads work; i.e., setting O_NONBLOCK using ioctl() will |
* Non-blocking reads work; i.e., setting O_NONBLOCK using ioctl() |
| cause an EAGAIN to be returned if there is no data ready. In |
will cause an EAGAIN to be returned if there is no data ready. In |
| addition, the select() and poll() functions will work correctly on | addition, the select() and poll() functions will work correctly on |
| emlog devices. | emlog devices. |
| | |
| |
* A small utility, 'nbcat', is included with the emlog distribution. |
| |
nbcat is similar to 'cat', but uses nonblocking reads. |
| |
This utility can be used to copy the current contents of an emlog |
| |
device without blocking to wait for more input. For example: |
| |
|
| |
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. |
| |
|
| | |
| Emlog and devfs | Emlog and devfs |
| =============== | =============== |
|
|
|
| Q: When I try to compile emlog, I get hundreds of errors related | Q: When I try to compile emlog, I get hundreds of errors related |
| to header files. | to header files. |
| | |
| A: If you've recently installed new kernel sources, make sure that |
A: If your kernel sources are rooted anywhere other than |
| you've run "make config" or "make menuconfig" in /usr/src/linux. You |
/usr/src/linux, make sure you change the KERNEL_HOME variable in the |
| don't actually have to go through the entire configuration; just make |
Makefile to reflect their location. If you've recently installed new |
| sure that you have a /usr/include/asm and a /usr/include/linux that |
kernel sources, make sure that you've run "make config" or "make |
| are symbolic links into your kernel source tree. |
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'. | Q: When I try to insert the module using 'insmod', I get 'I/O error'. |
| | |
| A: That probably means the major device number being registered by |
A: That usually means the major device number being registered by |
| emlog is already in use by another device driver. Try changing the |
emlog is already in use by another device driver. Type 'cat |
| major device number in emlog.h (or, change it to 0 in order to get a |
/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). | dynamically assigned major number). |
| | |
| | |
|
|
|
| by which processes. | by which processes. |
| | |
| | |
| Q: When more than one process tries to read data from an emlog device, |
Q: I am trying to save a copy of the current emlog buffer to another |
| only one gets it. |
file, by typing "cp /tmp/emlog-test /tmp/saved-log-copy", but cp just |
| |
sits there forever. |
| A: Yep, that's how it's supposed to work -- it differs from dmesg. |
|
| Unlike dmesg, emlog lets you block waiting for more input (like tail |
A: cp is blocked waiting for more data, just like 'cat' does when |
| -f). This was easier to implement by having buffers be consumed the |
used with an emlog device. Use 'nbcat', the non-blocking cat utility |
| first time they were read. |
included with the emlog distribution; for example: |
| |
nbcat /tmp/emlog-test > /tmp/saved-log-copy |
| | |
| | |
| Q: You've made my computer crash. | Q: You've made my computer crash. |
Return to
README
CVS log
Up to [CENS] / misc / emlog