log

--background_logresource--

Notes

This resource serves as a base interface to AROS's logging mechanisms.

It provides centralized collection and management of structured log messages
from system and application components, enabling uniform diagnostics and
analysis capabilities across the OS.

Messages are stored as dynamically allocated nodes
which are organized into two linked lists:
    - A global list maintained by the log.resource itself
    - A per-producer list

Entries are added using `logAddEntryA()` which supports a printf-style format string
and metadata such as component, subcomponent, originator, and event ID.

Each entry stores:
    - A human-readable formatted message (`le_Entry`)
    - Producer and originator info (`lep_Producer`, `lectx_Originator`)
    - Component tags (`le_Node.ln_Name`, `lep_Node.ln_Name`)
    - Time/date stamp (`le_DateStamp`)
    - Priority flags and event identifiers

Consumers may iterate over entries using `logNextEntry()` with an `entryHandle` pointer,
which is updated in place to walk through the list. Constants `LOGEntry_First` and
`LOGEntry_Last` mark the bounds of traversal.

Attributes of each entry can be queried with `logGetEntryAttrs()`, which takes a
taglist and returns selected fields such as LOGMA_Entry, LOGMA_Flags, LOGMA_Component,
and others.

Entries may be removed via `logRemEntry()`, which safely unlinks and deallocates
all associated resources, including copied strings.

`logLockEntries()` and `logUnlockEntries()` provide concurrency protection for
iteration or filtering.

The log.resource is self-contained and allocates memory via the producer's
memory pool (`lrh_Pool`) to simplify cleanup and ownership tracking.

logAddEntryA()

Synopsis

struct logEntry * logAddEntryA(
         ULONG flags,
         APTR loghandle,
         STRPTR sub,
         STRPTR src,
         ULONG eventid,
         STRPTR fmtstr,
         RAWARG fmtdata );

struct logEntry * logAddEntry(
         ULONG flags,
         APTR loghandle,
         STRPTR sub,
         STRPTR src,
         ULONG eventid,
         STRPTR fmtstr,
         TAG tag, ... );

Function

Creates and queues a new log entry associated with the given
logging handle. The entry includes timestamp, event ID,
optional subsystem/source strings, originator information,
and a formatted message string built from 'fmtstr' and 'fmtdata'.

Inputs

flags     - Logging flags and priority level (LOGM_*).
loghandle - Handle to an open log resource (struct LogResHandle *).
sub       - Optional subsystem string, may be NULL.
src       - Optional source string, may be NULL.
eventid   - User-supplied event identifier.
fmtstr    - Format string for the log message.
fmtdata   - Argument data matching the format string.

Result

Pointer to a logEntry structure if successful,
or NULL if the entry could not be created.

Example

struct logEntry *e = logAddEntryA(LOGM_Flag_Info, myLogHandle,
    "filesystem", "disk.device", 42,
    "Mounted volume %s", (RAWARG)"DH0:");

Notes

The returned logEntry is owned by log.resource and should not
be modified or freed by the caller. The timestamp source depends
on availability of DOS, timer.device, or kernel facilities.

Bugs

Kernel timestamp support is incomplete (marked TODO in source).