Controlling QNX helpers logging

Logging configuration syntax

The configuration string uses the following format:

context_name_1:destination[=severity_level,...];
context_name_2:destination[=severity_level,...];
context_nameN:destination[=severity_level,...]

It is made up of a series of key-value pairs separated by a semi-colon (;), without any newlines, spaces, tabs, or separating characters. The key and value are separated by a colon (:). The key is a context name and the value is the configuration to apply to the context. For information about context names, see “Setting up QNX helpers logging”. You can also specify one of the following reserved context names:

all — the specified configuration applies to all contexts except the default one.
default — update the default context with the specified configuration.

The value part of the key-value pair is itself made up of a series of key-value pairs separated by a comma (,) and the key and value are separated by an equal sign (=). The key specifies a logging destination and the value specifies the severity levels used for the verbosity. Valid destination keys are all, default, slog, slog2, stdout, and stderr. Valid severity level values are all, none, shutdown, critical, error, warning, notice, info, debug1, and debug2.

all — all logging destinations are assigned the value.
default — the context uses the values from the default context and a value cannot be specified. When the default context configuration changes, the values assigned by the default key also change. If you use default with the default context, the default context reverts back to the original defaults, as if it was never configured.
For all other destination keys, the value is optional (omit the equal sign). If no value is specified, the verbosity for the specified destination does not change.

When the key specifies a logging destination, it is used as an active destination (using its assigned verbosity, if you provide one) for the specified context. However, if the key is prefixed with a tilde (~), it is an inactive destination. Logging can still occur for destinations with this prefix if a log call specifically requests this destination and it meets the verbosity requirements.

The order of contexts and destinations can affect the logging behavior because the configuration is applied from left to right and contexts and destinations can be specified multiple times. The logging configuration that exists prior to making this call is not cleared before configuration updates are applied.

The configuration also applies to contexts that haven't been created yet. When a context is created, the configuration information is looked up and applied to it; otherwise, the context reverts to the default context's configuration.

There cannot be any white space in the configuration.

If there is a parsing error, the function returns an error and does not modify the logging configuration.

Example logging configurations

```
default:slog2=info;all:~stdout=none;qh:stdout=default 
```
1. Set the slog2 verbosity to QH_LOG_SEVERITY_INFO for the default context.
2. Specify that all other contexts should not use stdout as an active destination and set its verbosity to QH_LOG_SEVERITY_NONE. stdout is used only when a log call specifically requests it.
3. Specify that the qh context should use the settings from the default context for the stdout destination.
```
default:slog2=notice,~stderr=error 
```
1. Applies to the default context only.
2. Add slog2 as an active destination (with verbosity level QH_LOG_SEVERITY_NOTICE).
3. Make stderr an inactive destination and set its verbosity level to QH_LOG_SEVERITY_ERROR.
4. Leave the rest of the destinations and their associated verbosity unchanged.
```
all:~all=none,slog2=notice,~stderr=error 
```
1. Applies to all contexts except the default.
2. Make all destinations inactive and set their verbosity to none (i.e., don't log anything).
3. Add slog2 as an active destination with verbosity level QH_LOG_SEVERITY_NOTICE.
4. Keep stderr inactive but set its verbosity level to QH_LOG_SEVERITY_ERROR.
```
my_ctx:slog2 
```
1. Add slog2 as an active destination to the context my_ctx without changing its verbosity.
2. Leave the rest of the destinations and their associated verbosity unchanged.

Preventing applications from making changes to the logging configuration

If the environment variables contain QH_LOG_CONFIG_CTX, a program-specific configuration string (which uses the format QH_LOG_CONFIG_CTX__progname), or both, the library automatically uses them one after the other, starting with QH_LOG_CONFIG_CTX (if it is set and valid) to update the destination flags at startup, before the process enters its main function. The library then prevents that application from making any further changes. This behavior allows system integrators to set up the logging configuration the way they want without the possibility of the application changing it.

For development environments, where the implied locking can cause problems, you can disable the locking behavior by setting QH_LOG_CONFIG_LOCKED to 0.

QH_LOG_CONFIG_CTX__`progname`

The program-specific environment variable allows system integrators to have system-wide settings in QH_LOG_CONFIG_CTX and program-specific settings in QH_LOG_CONFIG_CTX__progname.

The QH_LOG_CONFIG_CTX__progname environment variable is made up of:

QH_LOG_CONFIG_CTX__ (suffix is two underscores).
The program name as reported by __progname. If the first character or any other characters are non-alphanumeric, they are converted to an underscore. The name is truncated to 63 characters. The case of the characters is preserved. For example, if __progname is 03aB[-t, the environment variable associated with it is QH_LOG_CONFIG_CTX___3_aB__t.

Configuring slog2

System integrators can use the environment variable QH_LOG_CONFIG_SLOG2 or QH_LOG_CONFIG_SLOG2__progname (which uses the same naming convention as QH_LOG_CONFIG_CTX__progname) to configure the set of slog2 buffers that QNX helpers uses. If these environment variables are used, QNX helpers uses only one of them, because having a combined or successive application of multiple slog2 configurations doesn't make sense. It first tries to use QH_LOG_CONFIG_SLOG2__progname, and if it is absent or invalid, it uses the system-wide one if it is present and valid. If neither environment variable is present and valid, it creates three slog2 buffers to use by default:

high - For logs with severity levels QH_LOG_SEVERITY_WARNING and above. Its size is four slog2 pages.
low - For logs with severity levels below QH_LOG_SEVERITY_WARNING. Its size is eight slog2 pages.
default - For slog2 calls made directly through the slog2 API. Not for use with QNX helpers. It sets the specified buffer to NULL, which means use the default buffer. This buffer has a single page.

The configuration string noslog2 completely disables slog2 for QNX helpers logging (i.e., no buffer sets are created and no logging to slog2 happens through QNX helpers).

Registration of the slog2 buffers is delayed until the first QNX helpers log call that logs to slog2 is made, with the following exceptions:

Only the default buffer has any buffer pages. In this case, if registration isn't done early, it never occurs because no QNX helper logs ever go to slog2 (the normal trigger for slog2 registration).
The configuration string contains early_init, which indicates that the slog2 registration should not be delayed.

In cases where QNX helpers should configure slog2, the configuration string is a series of key-value pairs separated by a semi-colon (;). Each key-value pair is separated by a colon (:). The key is one of high, low, default, or flags and the value is the configuration:

key1:value1;...;keyN:valueN

Although the order in which sections appear is not important and they are all optional, at least one key-value pair is required. When one isn't specified, QNX helpers uses the default values described above.

The `flags` key

The flags key specifies a set of slog2 flags to use when registering the slog2 buffer set. By default, QNX helpers doesn't use any flags when it registers the slog2 buffer set. The value for flags is a comma-separated list of flag names. Possible values are:

alloc_phys — Equivalent to SLOG2_ALLOC_TYPE_PHYSICAL.
alloc_shmem — Equivalent to SLOG2_ALLOC_TYPE_SHMEM.
discard_newline — Equivalent to SLOG2_DISCARD_NEWLINE.

For more information on these flags, see slog2_register() in the C Library Reference.

The `high`, `low`, and `default` keys

The high, low, and default keys each represent a slog2 buffer configuration. Their value is a comma-separated list of options. As mentioned above, the high buffer gets the logs with higher severity, low gets those that don't make it to the high buffer, and default gets the logs from slog2 calls that were made directly through the slog2 API (buffer value is NULL). The following buffer configuration options are available:

For all sections:
- pages=X — X represents the number of 4 KB pages to allocate for the specified buffer. If this option isn't specified, the default number of pages is used (four for the high buffer, eight for low, and one for default).
For the high buffer section:
- minsev=severity — The severity value represents the severity level at which messages start being logged to the high severity buffer. Messages below this severity go to the low severity buffer. Valid values are: all, none, shutdown, critical, error, warning, notice, info, debug1, or debug2. When none is used, a single buffer logs all messages and there is no low and high buffer. To use none, the pages configuration option for the high buffer must be set to 0. When all or debug2 is used, it also means use a single buffer, but pages must not be 0 for the high buffer. If minsev is not specified, the severity level at which messages start being logged to the high severity buffer is warning.
For the high and low buffer sections:
- isdefault — When the isdefault option is specified, it means that there is no default slog2 buffer for messages logged through slog2 directly. Instead, those messages go to the buffer that has the isdefault option.

White spaces

Do not put any white spaces in the slog2 configuration.

Parsing errors

If there is an error when the slog2 configuration is parsed from QH_LOG_CONFIG_SLOG2, a corresponding message is logged and QNX helpers uses the following default configuration for the slog2 buffers:

A high buffer with four pages, minsev is warning.
A low buffer with eight pages, a one-page default buffer, and no flags.

Example slog2 configurations

high:pages=5,minsev=notice;low:isdefault;flags:alloc_shmem,discard_newline

The high buffer gets five pages and is sent all messages with notice severity and above.
The low buffer gets the default number of pages (eight) and is also used as the default buffer for non-QNX helpers slog2 calls. The SLOG2_ALLOC_TYPE_SHMEM and SLOG2_DISCARD_NEWLINE flags are used.

high:minsev=error;default:pages=5

The high buffer gets the default number of pages (four) and is sent all messages with error severity and above.
The low buffer gets the default number of pages (eight) and the default buffer gets five pages.