|
LibreOffice Module sal (master) 1
|
Macros for logging.
SAL_INFO(char const * area, expr), SAL_INFO_IF(bool condition, char const * area, expr), SAL_WARN(char const * area, expr), SAL_WARN_IF(bool condition, char const * area, expr), and SAL_DEBUG(expr) produce an info, warning, or debug log entry with a message produced by piping items into a C++ std::ostringstream. The given expr must be so that the full expression "stream << expr" is valid, where stream is a variable of type std::ostringstream.
SAL_INFO("foo", "string " << s << " of length " << n)
would be an example of such a call.
The composed message should be in UTF-8 and it should contain no vertical formatting characters and no null characters
For the _IF variants, log output is only generated if the given condition is true (in addition to the other conditions that have to be met).
The SAL_DEBUG macro is for temporary debug statements that are used while working on code. It is never meant to remain in the code. It will always simply output the given expression in debug builds.
For all the other macros, the given area argument must be non-null and must match the regular expression
<area> ::= <segment>("."<segment>)*
with
<segment> ::= [0-9a-z]+
For a list of areas used see SAL debug areas. Whenever you use a new log area, add it to the file include/sal/log-areas.dox .
Whether these macros generate any log output is controlled in a two-stage process.
First, at compile time the macros SAL_LOG_INFO and SAL_LOG_WARN, respectively, control whether the INFO and WARN macros, respectively, expand to actual code (in case the macro is defined, to any value) or to no-ops (in case the macro is not defined).
Second, at runtime the environment variable SAL_LOG further limits which macro calls actually generate log output. The environment variable SAL_LOG must either be unset or must match the regular expression
<env> ::= <switch>*
with
<switch> ::= <sense><item>
<sense> ::= "+"|"-"
<item> ::= <flag>|<level>("."<area>)?
<flag> ::= "TIMESTAMP"|"RELATIVETIMER"|"FATAL"
<level> ::= "INFO"|"WARN"
If the environment variable is unset, the setting "+WARN" is assumed instead (which results in all warnings being output but no infos). If the given value does not match the regular expression, "+INFO+WARN" is used instead (which in turn results in everything being output).
The "+TIMESTAMP" flag causes each output line (as selected by the level switch(es)) to be prefixed by a timestamp like 2016-08-18:14:04:43.
The "+RELATIVETIMER" flag causes each output line (as selected by the level switch(es)) to be prefixed by a relative timestamp in seconds since the first output line like 1.312.
The "+FATAL" flag will cause later matching rules to log and call std::abort. This can be disabled at some later point by using the "-FATAL" flag before specifying additional rules. The flag will just abort on positive rules, as it doesn't seem to make sense to abort on ignored output.
If both +TIMESTAMP and +RELATIVETIMER are specified, they are output in that order.
Specifying a flag with a negative sense has no effect. Specifying the same flag multiple times has no extra effect.
A given macro call's level (INFO or WARN) and area is matched against the given switches as follows: Only those switches for which the level matches the given level and for which the area is a prefix (including both empty and full prefixes) of the given area are considered. Log output is generated if and only if among the longest such switches (if any), there is at least one that has a sense of "+". (That is, if both +INFO.foo and -INFO.foo are present, +INFO.foo wins.)
If no WARN selection is specified, but an INFO selection is, the INFO selection is used for WARN messages, too.
For example, if SAL_LOG is "+INFO-INFO.foo+INFO.foo.bar", then calls like SAL_INFO("foo.bar", ...), SAL_INFO("foo.bar.baz", ...), or SAL_INFO("other", ...) generate output, while calls like SAL_INFO("foo", ...) or SAL_INFO("foo.barzzz", ...) do not.
The generated log output consists of the optional timestamp, the given level ("info" or "warn"), the given area, the process ID, the thread ID, the source file, and the source line number, each followed by a colon, followed by a space, the given message, and a newline. The precise format of the log output is subject to change. The log output is printed to stderr without further text encoding conversion.
On some systems, log output can be redirected to other log sinks, notably a file provided as a system path and filename via environment variable SAL_LOG_FILE; or to a syslog facility if LibreOffice is suitably built, by setting environment variable SAL_LOG_SYSLOG.
1.9.3