Go to the previous, next section.

System Log Daemon

Introduction

The System Message Log Daemon (syslogd) allows logging of messages from the kernel and other modules to go to a system log file. It allows different levels of logging and the ability to start and stop message logging altogether. Modules can open private handles to the log daemon to allow them to write debugging, status and any other information they want to the logfile. The level of message logging can also be set to avoid producing a log file that gets too big with normal usage of the operating system whilst allowing all needed information to be logged when the operating system and its modules are being debugged. The spool file is defined in the header `<vmm/syslogd.h>' and is by default set to `/adm/syslog'.

Operation

Upon initialisation, syslogd creates a thread to handle the operation of writing the log messages to the log file. This is done for two reasons:

It stops modules which are using the log facility from slowing down whilst their information is written to the file.
It allows interrupt and exception handlers to log messages because the thread which is writing to the disk is running in a different context. If this were not done, interrupt and exception handlers would not be able to log messages.

Messages are added to the log file by the functions syslogd_entry and syslogd_cooked_entry. These messages are then added into a circular buffer, the contents of this buffer being written to the log file by the thread previously created. This situation of two threads accessing a circular buffer is a classic of the `producer-consumer' relationship and simultaneous access to the circular buffer is prevented by the use of a semaphore.

Messages are only entered into the circular buffer if two conditions are fulfilled:

Logging is currently enabled and,
The level of the message if less than or equal to the current logging level.

Functions

Opening The Log

Before a program can write to the logfile, it must open it to gain a handle to write to.

syslogd Function: int open_syslog (char *name, u_int level)

This function gives a process access to the log.

name is a string of maximum length 16 characters used as an identifier in the log output.

level is the logging level at which this output is written to the log.

This function returns -1 on error or the handle used for access.

Closing The Log

When a program has finished with the logfile, it should close it to free up its handle.

syslogd Function: void close_syslog (int handle)

This function closes and frees access to the logfile.

handle is the handle returned by open_syslog.

This function returns nothing.

Once a program has gained a handle, it can then write its entries to the logfile using one of the following two functions.

Writing To The Log

syslogd Function: void syslog_entry (int handle, char *entry)

Adds a string to the logfile. The string is time-stamped and preceded by the identification string given when the logfile was opened.

handle is the handle returned by open_syslog.

entry is the string to add.

This function returns nothing.

syslogd Function: void syslog_cooked_entry (int handle, char *entry)

Adds a string to the logfile. No other information is added to the string. This is used for putting preformatted data into the logfile and is primarily used by the kernel's printk function for writing its internal buffer to the logfile.

handle is the handle returned by open_syslog.

entry is the string to add.

This function returns nothing.

Controlling The Logging

The action of the Log Daemon can be controlled in two ways:

Disabling or enabling logging entirely and,
Setting the logging level.

syslogd Function: void syslog_start (void)

This function enables logging to start. If logging is not enabled no messages will be written to the logfile.

This function returns nothing.

syslogd Function: void syslog_stop (void)

This function disables logging. No messages can be written to the logfile.

This function returns nothing.

syslogd Function: void set_syslog_level (u_int level)

This function sets the current logging level.

level is the new logging level.

This function returns nothing.

Status Of The Log Daemon

A program can gain information about the Log Daemon to find out how many messages and characters have been written, whether logging is enabled and the current logging level.

syslogd Function: void syslog_status (struct syslog_status *status)

Obtain status information about the current state of the Log Daemon.

status is filled with information about the state of the Log Daemon.

This function returns nothing.

Example Function Usage

To access the log file use a piece of code something like the following.

#include <vmm/syslogd.h>

...

int handle;

/* open the syslog with an identifier of `name' and level
   2 logging */
if((handle = syslogd->open_syslog("name", 2)) != -1) {

    /* function succeeded */
    syslogd->syslog_entry(handle, "log entry");

    /* add a string which will not be time stamped or
       identified */
    syslogd->syslog_cooked_entry(handle, "direct entry");
    syslogd->close_syslogd(handle);

} else {

    /* function failed */
    ...

}

To get the status of the log daemon and control its operation, use the syslog_status, syslog_start, syslog_stop and set_syslog_level functions.

#include <vmm/syslogd.h>

...

/* get the status of the log daemon, increase the logging level
   by 1 and toggle its operational state. */
struct syslog_status status;

/* get the status */
syslogd->syslog_status(&status);

/* increase the logging level */
syslogd->set_syslog_level(status.log_level + 1);

/* toggle the operation of the daemon */
if(status.enabled == TRUE)
    syslogd->syslog_stop();
else
    syslogd->syslog_start();

Go to the previous, next section.