write-to-system-log

format-to-system-log Functions

Summary

Write a message to the operating system log.

Package

hcl

Signatures

write-to-system-log message &key priority tag &allow-other-keys

format-to-system-log priority tag format-control-string &rest format-args

Arguments

message⇩	A string.
priority⇩	A Lisp object. Default :info.
tag⇩	A string.
format-control-string⇩
	A string.
format-args⇩	Lisp objects.

Description

The functions write-to-system-log and format-to-system-log write messages to the log of the underlying operation system. format-to-system-log first calls safe-format-to-string with format-control-string and format-args to generate the message, and then calls write-to-system-log with the message, priority, and tag. write-to-system-log does the actual writing as specified below.

Implementation on Operating systems other than Android and Windows

On operating systems other than Android and Windows, the writing is done using the C function syslog.

If priority is one of the keywords :error, :debug or :warn, then the priority argument to syslog is LOG_ERR, LOG_DEBUG or LOG_WARN respectively. priority :warning also uses LOG_WARN. For all other values of priority, LOG_INFO is used.

The format string for syslog is always "%s".

The first argument to the format string is a string generated by appending tag, colon, space and message. tag defaults to the result of lisp-image-name.

If message is long, it is split to sub-strings, with each sub-string written by a separated call to syslog. tag is only prepended to the first sub-string.

Implementation on Windows

On Windows, the writing is done using the C function ReportEvent.

tag is used to create the event log handle (the first argument to ReportEvent) by passing it as the source name to RegisterEventSource. tag defaults to the result of lisp-image-name.

If priority is one of the keywords :error or :warn, the type argument to ReportEvent is EVENTLOG_ERROR_TYPE or EVENTLOG_WARNING_TYPE respectively. priority :warning also uses EVENTLOG_WARNING_TYPE. For all other values of priority, EVENTLOG_INFORMATION_TYPE is used.

Implementation on Android

On Android, the writing is done using the C function __android_log_write, which has the same effect as using that methods in the Java class android.util.Log.

tag is used the tag argument for __android_log_write. It defaults to "LispWorks".

If priority is one of the keywords :error, :debug, :warn or :verbose, the prio argument to __android_log_write is ANDROID_LOG_ERROR, ANDROID_LOG_DEBUG, ANDROID_LOG_WARN, or ANDROID_LOG_VERBOSE respectively. priority :warning also uses ANDROID_LOG_WARN. For all other values of priority, ANDROID_LOG_INFO is used.

Notes

These functions where added initially for Android, where they are useful for debugging because they add messages to the logcat.