4.31.2 Logging programming interface

The following bindings are exported by the library (vicare posix log-files).

Function: open-logging

If logging is enabled: configure the log port; return unspecified values. If the selected pathname is - assume the log messages must go to the current error port. Otherwise open a log file.

This function makes use of the following parameters:

logging-enabled?

If set to true consider logging enabled, else do nothing and return.

log-pathname

Used to retrieve the configured log file pathname.

log-port

Used to store the Scheme textual output port to which log messages are sent.

Function: close-logging

Close the current log port unless it is the console error port or the configured log file pathname is a single dash; return unspecified values.

This function makes use of the following parameters:

log-pathname

Used to retrieve the configured log file pathname and check if it is a single dash.

log-port

Used to retrieve current log port.

Notice that the logging-enabled? parameter is ignored.

Function: setup-compensated-log-file-creation

Call open-logging and push a call to close-logging on the current compensations stack.

Function: log template arg …

If logging is enabled: format a log message and write it to the current log port; return unspecified values.

template must be a format–like string expecting as many values as there are arg arguments. It is usual, but not mandatory, to output log messages as single lines.

A log message is composed as follows:

1. The current prefix referenced by the parameter log-prefix.
2. A date string, almost in ISO 8601 format.
3. A colon character followed by a space character.
4. The result of formatting template with the given arg arguments.
5. A newline character.

Function: log-condition-message template condition

If logging is enabled: format a log message extracting the message from the condition object condition; return unspecified values. The template is expected to contain a ~a sequence to be replaced by the condition message.

Syntax: with-logging-handler (condition-message ?template) ?body0 ?body …

Auxiliary Syntax: condition-message

Evaluate the ?body forms; in case of exception: log a message with log-condition-message and raise it again.

condition-message must be the identifier exported by the library (rnrs rnrs (6)). ?template must be an expression evaluating to a string template suitable to be used as first argument to log-condition-message.