SysLog

Log Names and Files

Each normal log is identified by a log name. The name is used directly as the leafname of the file stored in SysLog$LogDir, so the name must be a valid RISC OS leafname and must not exceed ten characters. The implementation rejects empty names and names containing ., :, *, #, $, &, @, ^, %, or \.

The original SysLog documentation reserves the following names for SysLog itself:

• any name beginning with -;
• any name beginning with SysLog; and
• Old.

Applications should treat those names as unavailable even though the module only enforces the general leafname rules directly.

The intended convention is that each application has its own log, usually named after the application without any leading !. Very large applications may use more than one log, but they should still choose names that are stable and recognisable to the user.

The original documentation also recommended allocating distributed log names formally so that unrelated applications did not collide on the same log file. The module itself does not enforce such a registry, but applications should still avoid reusing names already associated with other software.

Priorities and Thresholds

Message priorities are integers in the range 0 to 255, where 0 is the highest priority and 255 is the lowest. Log thresholds are compared using a strict less-than test:

• if message_priority < log_threshold, the message is recorded;
• if message_priority >= log_threshold, the message is discarded without error.

A threshold of 256 therefore disables ordinary logging for that log while still allowing callers to query or alter the threshold. The command parser for *SysLog accepts thresholds in the range 0 to 256.

In practice, priorities around 100 suit ordinary day-to-day information. Non-critical chatter should generally avoid the very high-importance range below about 50. The original guidance characterised priority 10 as comparable to Government declares war, priority 0 as Armageddon imminent, and priority 255 as Water detected in ocean. Those examples are informal, but they express the intended spread of the scale clearly.

Applications should choose priorities based on the effect of the condition on the user, not merely its technical cause. An out-of-memory condition can be a startup-fatal error in one context and an unimportant transient condition in another.

Log File Format

The basic logging primitive stores one line of text terminated by a line-feed. SWI SysLog_LogMessage prepends a textual timestamp, a three-digit priority field, and indentation spaces. SWI SysLog_LogUnstamped stores the supplied text without that prefix. The module stops copying at the first zero byte, line-feed, or carriage return in the supplied string.

Indented logging is cumulative per log. The indent level starts at zero, SWI SysLog_Indent increments it up to a maximum of 32, SWI SysLog_UnIndent decrements it down to zero, and SWI SysLog_NoIndent resets it immediately.

Options File

SysLog reads its configuration from the plain text file <SysLog$Dir>.Options when the module initialises. The standard !SysLog.!Boot file sets SysLog$Dir to the application directory, so the distributed options file lives in !SysLog.Options.

Each options line begins with a log name. The special name * supplies defaults used for logs that do not have a matching explicit line.

The recognised syntax is:

logname [Reserve kilobytes | NoReserve] [Sessions | NoSessions]
        [threshold [max_size_kilobytes [timeout_centiseconds]]]

The supplied sample file documents only the first four fields, but the source also accepts an optional fifth numeric field. That final number becomes the flush timeout, measured in centiseconds, for that log. If it is omitted, the default is 50 centiseconds, or half a second.

The options have these effects:

• Reserve causes SysLog to keep extra space allocated at the end of the file. The value is stored in bytes, but the file syntax is in kilobytes.
• NoReserve disables reserved-space management for that log.
• Sessions enables temporary session logs for the log.
• NoSessions causes session logging requests to fall back to direct logging in the main log.
• threshold sets the log threshold used by priority filtering.
• max_size_kilobytes sets the maximum size of the main log before it is rotated to Old.<logname>.
• timeout_centiseconds sets the inactivity period after which buffered output is flushed automatically.

SysLog expands SysLog$Dir and SysLog$LogDir once at startup and caches the options file in memory. Editing the file does not affect the running module until it is reloaded.

Buffering and Rotation

Each log may have an in-memory buffer. SysLog chooses the buffer size from the current threshold:

• threshold 0 to 100: 1024 bytes;
• 101 to 125: 2048 bytes;
• 126 to 150: 4096 bytes;
• 151 to 175: 8192 bytes;
• 176 to 200: 16384 bytes; and
• 201 to 256: 32768 bytes.

That choice makes the lowest-priority, most verbose logs the cheapest to use. Buffers are allocated lazily, flushed after the per-log timeout expires, and released after ten minutes of inactivity or when SWI SysLog_LogComplete is called.

When a main log exceeds its configured maximum size, SysLog truncates it to the last real byte of data, deletes any existing Old.<logname>, renames the current log to that old-file name, and starts a fresh current log. Temporary session logs are handled differently: if a session log grows too large and SysLog knows its parent log, the temporary file is deleted and recreated instead of being rotated.

Session Logs

Session logs are created by SWI SysLog_OpenSessionLog. Despite the historic documentation calling the return value a session log handle, the returned handle is actually a pointer to a temporary log name string. That temporary log name begins with - and names the temporary file used under SysLog$LogDir.

When a session log is opened, SysLog writes the parent log name and a blank line at the start of the temporary file, then writes a session marker line. When the session is closed by SWI SysLog_CloseSessionLog, SysLog appends the whole temporary file to the main log and deletes the temporary file.

Applications can usually treat the returned value opaquely:

• if the requested priority is not being logged, SWI SysLog_OpenSessionLog returns 0 and later SWIs ignore that null handle;
• if sessions are disabled for the parent log, SWI SysLog_OpenSessionLog returns the original log name instead of creating a temporary file; and
• SWI SysLog_CloseSessionLog safely does nothing when given an ordinary log name instead of a temporary session name.

At module initialisation and finalisation SysLog scans the log directory for stray temporary files whose names begin with -. Any it finds are merged back into their parent logs automatically.

IRQ Mode

Normally SysLog may flush buffers and touch the filing system while handling a log request, so the logging SWIs are not safe from interrupt handlers. Calling SWI SysLog_IRQMode with a non-zero value places the module in IRQ mode. In that mode SWI SysLog_LogMessage, SWI SysLog_LogUnstamped, SWI SysLog_LogData, and SWI SysLog_LogFormatted only append to in-memory buffers.

If a buffer fills while IRQ mode is active, the new message is dropped and a missed-message count is recorded. Once IRQ mode is no longer active, SysLog inserts a line reporting how many log lines were missed.

IRQ mode is reference-counted. Each non-zero call increments the counter and each zero call decrements it down to zero. Applications which enable IRQ mode must disable it again when the critical section ends.

The following SWIs are always safe from interrupt code because they do not need to flush buffered data:

• SWI SysLog_GetLogLevel
• SWI SysLog_Indent
• SWI SysLog_UnIndent
• SWI SysLog_NoIndent
• SWI SysLog_ReadErrorMessage

Formatted Logging and the C Veneer

SWI SysLog_LogFormatted provides a low-level formatter primarily for assembler code. It builds a line in an internal scratch buffer and then writes it as a normal stamped log message. The format language is deliberately small and is described in the SWI definition.

The original source distribution also supplies a C veneer in !SysLog.C-veneer. The header h.syslog declares one non-X and one X form for each exported SWI, plus the convenience functions syslogf and xsyslogf. Those two helper functions format a string with vsprintf and then call SWI SysLog_LogMessage.

The C veneer documentation warns that its temporary formatting buffer is only 1024 bytes long. The assembled veneer source actually reserves 1536 bytes, but portable code should continue to treat 1024 bytes as the safe upper limit because the SysLog text interfaces themselves truncate logged strings to 1024 bytes.

The veneer exports the following entry points:

• non-X calls: syslog_logmessage, syslog_getloglevel, syslog_flushlog, syslog_setloglevel, syslog_logunstamped, syslog_indent, syslog_unindent, syslog_noindent, syslog_opensessionlog, syslog_closesessionlog, syslog_logdata, syslog_readerrormessage, syslog_logcomplete, syslog_irqmode, and syslogf;
• X calls: xsyslog_logmessage, xsyslog_getloglevel, xsyslog_flushlog, xsyslog_setloglevel, xsyslog_logunstamped, xsyslog_indent, xsyslog_unindent, xsyslog_noindent, xsyslog_opensessionlog, xsyslog_closesessionlog, xsyslog_logdata, xsyslog_readerrormessage, xsyslog_logcomplete, xsyslog_irqmode, and xsyslogf.

The non-X forms are usually more convenient for application code because they return ordinary values directly. The X forms are intended for code that must handle errors explicitly, such as modules and other low-level components.

Application Startup

The simplest usage pattern is to choose a stable log name, query the threshold if constructing the message would be expensive, and then log the important events:

IF SYS("SysLog_GetLogLevel", "MyApp") > 100 THEN
  SYS "SysLog_LogMessage", "MyApp", "Initialising network stack", 100
ENDIF

Scoped Session Logging

Session logging lets an application group all the activity for one connection, job, or transaction and then merge it back into the main log as a block:

session = SysLog_OpenSessionLog("NewsBite", 110)
SysLog_LogMessage(session, "Connection accepted", 110)
SysLog_LogData(session, 120, packet, packet_length, 0)
SysLog_CloseSessionLog(session)

Assembler LogFormatted Wrapper

The usual assembler style is to package SWI SysLog_LogFormatted behind a small macro or helper routine:

STMFD   R13!,{R0-R3,R8-R12,R14}
ADR     R0,txt_logname
ADR     R1,%ft90
MOV     R2,#200
MOV     R3,R13
SWI     SysLog_LogFormatted
B       %ft91
90
=       "stricmp: comparing %0z and %1z",0
ALIGN
91
LDMFD   R13!,{R0-R3,R8-R12,R14}

This keeps the call site short and ensures that the register block passed in R3 matches the format-string references.

Using the C Veneer

The supplied header and veneer object let C code call SysLog without writing manual SWI veneers:

#include "kernel.h"
#include "syslog"

if (syslog_getloglevel("MyApp") > 100)
  syslog_logmessage("MyApp", "Starting up", 100);

syslogf("MyApp", 90, "Connected peer %s on handle %d", host, handle);

Programs should link against the supplied veneer object that matches their APCS requirements. The original distribution provided both a 26-bit/APCS-3 veneer and an APCS-32 veneer object.

Representative Options File

The distributed options file uses one default line and then selective overrides:

* NoReserve Sessions 125 256
Termite NoSessions
NewsBite 125
NewsBite-d 256 1024

That example means that most logs inherit a threshold of 125, no reserved space, sessions enabled, and a 256 KB maximum size; the listed logs then override individual parts of that policy.