===
log
===

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`--background_logresource--`_           `logAddEntryA()`_                       
======================================= ======================================= ======================================= ======================================= 

-----------

--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).



