# dklibs 1.23.1

- Overview
- Download
- Installation
- Installation from source on Windows systems
- Usage
- FAQ
- Change log
- Other projects
- Tutorial
- Developer docu
- stc
- tracecc and trana
- tracecc GUI
- tracecc PDF man.
- API: sort and search
- API: Generic I/O
- Preferences
- File search
- Font configuration
- LaTeX encodings
- Security

## Preferences

- Overview
- Sources and scopes
- Preferences storage and maintenance
- Preferences storage on Unix/Linux
- Preferences storage on Windows systems
- Common preferences
- Language and localization
- Resource search
- Temporary files
- Logging
- Performance
- Security
- Random number generation
- Macros in preferences
- Examples
- Unix/Linux examples
- Windows examples

### Overview

Preferences are key/value pairs used to store configuration settings. Both key and value are text strings. The key consists of three components:

- Source
  There are different sources for configuration settings:
  - system-wide settings created by an administrator,
  - user-made settings,
  - command line options and
  - entries created by an application itself.
- Scope
  A configuration setting can be valid in different situations, depending on the user running a program, the application asking for a setting and the host the program is running on.
- Name
  The name uniquely identifies a setting.

### Sources and scopes

By default all sources for configuration settings are inspected to find an entry. Only for security-relevant settings (settings forcing a program to skip security checks) programs should use command line options only.

If user "joe" runs application "myapp" on host "pc-joe" and the application needs the users preferred language, it attempts to get the preference value "/ui/lang" (user interface, language) from the following scopes:

joe/myapp/pc-joe |  | valid for user joe running application on host pc-joe
joe/myapp/* |  | valid for user joe running myapp on any host
joe/*/pc-joe |  | valid for user joe running any application on host pc-joe
joe/*/* |  | valid for user joe running any application on any host
*/myapp/pc-joe |  | valid for any user running myapp on host pc-joe
*/myapp/* |  | valid for any user running myapp on any host
*/*/pc-joe |  | valid for any user running any application on host pc-joe
*/*/* |  | valid for any user running any application on any host

The first (most detailed) scope has highest priority, the last scope has lowest priority.
If there are different sources providing entries for the highest priority scope, the sources are used in the order

- internal settings created by the program (highest priority),
- command line options,
- user-specific settings,
- system-wide settings (lowest priority).

### Preferences storage and maintenance

#### Preferences storage on Unix/Linux

Preferences are stored in files with an ini-file like syntax. Scopes given in square brackets are valid for all configuration settings following that scope until the next scope specification is found.

- System-wide settings
  System-wide settings are stored in ${sysconfdir}/appdefaults and/or ${sysconfdir}/appdefaults.appname (settings of interest for one application only). Scopes in ${sysconfdir}/appdefaults include user name, application name and host name. Scopes in ${sysconfdir}/appdefaults.appname include user name and application name only.
  Example for ${sysconfdir}/appdefaults:

      # for all users running any application on any host
      [*/*/*]
      # set the default language
      /ui/lang		=	en_US
      # ignore the LANG environment variable
      /ui/lang/env	=	off

      # user otto is coming from Germany...
      [otto/*/*]
      /ui/lang		=	de_DE

  Example for ${sysconfdir}/appdefaults.appname

      # valid for all users on all hosts
      [*/*]
      /dir/app	=	/usr/local/myapp

  It's good practice to have settings of general interest (language selection, logging...) in ${sysconfdir}/appdefaults.
  The ${sysconfdir}/appdefaults.appname files should be used for very program-specific settings only. An example is ${sysconfdir}/appdefaults.createp containing password types for the createp programs. These password types are of no interest for any other program so there is no need for other programs to waste memory by loading these preferences.
- User-specific settings
  User-specific settings are stored in $HOME/.defaults/all or $HOME/.defaults/appname (settings of interest for one application only).
  Scope specifications in $HOME/.defaults/all include application name and optionally a host, scope specifications in $HOME/.defaults/appname include a host name only.
  Example for a $HOME/.defaults/all file:

      # my personal settings for all programs
      [*]
      /log/stdout/level		=	none
      /log/stderr/level		=	info

      # for myapp I want detailed info
      [myapp]
      /log/stderr/level		=	debug

  Example for a $HOME/.defaults/appname file (a $HOME/.defaults/createp file here):

      /password/wlan-key/ascii85	=	on
      /password/wlan-key/capitals	=	0
      /password/wlan-key/digits	=	2
      /password/wlan-key/length	=	128
      /password/wlan-key/passwd-only	=	off
      /password/wlan-key/specials	=	0
      /password/type	=	user
      /password/user/ascii85	=	off
      /password/user/capitals	=	0
      /password/user/digits	=	2
      /password/user/length	=	6
      /password/user/passwd-only	=	off
      /password/user/specials	=	0

The $HOME/.defaults/all file is maintained by the user manually.
The $HOME/.defaults/appname files are created, modified or removed by applications if the -c or -u option is used.
If there is a key/value pair before the first scope specification or there is no scope specification at all, settings are in the lowest priorized scope ("*/*/*". "*/*" or "*").

#### Preferences storage on Windows systems

On Windows systems the registry is used to store preferences.
The preferences storage in the registry was changed significantly in dklibs version 1.17.0.
The purpose is to avoid unnecessary typing of scopes in registry entry names and to allow some preferences to "survive" a --unconfigure operation.

- System-wide settings
  System-wide settings are stored in HKLM\Software\DkApp (for all applications) and the HKLM\Software\DkApp\appname subkeys (application specific).
  The registry entry names in HKLM\Software\DkApp consist of the scope specification (user name, application name and host name separated by slashes) and the preference name, separated by a colon. The "all" wildcard can be used for all users/all applications/all hosts. Trailing "all" wildcards must be omitted, so the entry name for preference "/ui/lang" in scope "joe/all/all" is "joe:/ui/lang". The entry name for preference "/ui/lang" in scope "all/all/all" is simply "/ui/lang".
  The scope specification in entry names in HKLM\Software\DkApp\appname consists of user name and host name, i.e. "joe/my-pc:/ui/lang". Trailing "all" components in the scope must be omitted.
- User-specific settings
  User-specific settings are stored in HKCU\Software\DkApp and the HKCU\Software\DkApp\appname subkeys.
  The scope specification is application name and host name (for HKCU\SoftwareDkApp) or just the host name (for HKCU\Software\DkApp\appname). Trailing "all" components in the scope must be omitted.

### Common preferences

#### Language and localization

Name | Source | Programs | Contents
--- | --- | --- | ---
/ui/lang | any | any | language code language_country.encoding, i.e. en_US or de_DE.UTF-8
/ui/lang/env | any | any | boolean value (i.e. "on" or "off"), indicates whether or not the LANG environment variable overrides the setting in /ui/lang.

#### Resource search

Name | Source | Programs | Contents
--- | --- | --- | ---
/dir/app | any | any | the application-specific directory to search for resources
/dir/shared | any | any | the directory to search for resources shared by multiple applications

#### Temporary files

Name | Source | Programs | Contents
--- | --- | --- | ---
/dir/tmp | any | any | base directory for temporary files (each application process creates a subdirectory)
/dir/tmp/keep | any | any | boolean value to indicate whether or not the processes temporary directory is kept (not deleted) when the program calls dkapp_close() before exiting. By default temporary directories are removed. Sometimes you may want to keep them for debugging purposes.

#### Logging

Name | Source | Programs | Contents
--- | --- | --- | ---
/log/file/name | any | any | name of the log file to create
/log/file/level | any | any | minimum priority of messages to be logged to file (lower priority messages are skipped), may be "none", "panic", "fatal", "error", "warning", "info", "progress" or "debug". The recommended range is "error" ... "progress".
/log/file/keep | any | any | minimum priority of messages required to keep the log file. By default the log file is deleted if the application calls dkapp_close() before exiting. Sometimes you may want to keep the log file for debugging purposes.
/log/file/codepage | any | any | codepage to use for log messages going to file
/log/file/time | any | any | boolean value to indicate whether or not to write time stamps with log messages
/log/file/split | any | any | boolean value to indicate whether or not to create separated lines for time stamps (if time stamp printing is enabled)
/log/file/ide | any | any | output lines can imitate the style of some widely used developer tools for better integration with make or IDEs. Use one of the following values: none normal behaviour gcc to behave like Gnu C compiler msvc to behave like MS Visual C++ 5.0 compiler workshop to behave like Sun Workshop C compiler tasm to behave like Borland C 3.1's Turbo Assembler
/log/stdout/level /log/stdout/time /log/stdout/split /log/stdout/codepage /log/stdout/ide /log/stderr/level /log/stderr/time /log/stderr/split /log/stderr/codepage /log/stderr/ide | any | any | settings for logging to stdout and stderr. See /log/file/... above.

#### Performance

Name | Source | Programs | Contents
--- | --- | --- | ---
/storage/trees | any | any | boolean value, indicates whether or not tree structures can be used for sorted containers. You should leave this setting at the builtin defaults.

#### Security

Name | Source | Programs | Contents
--- | --- | --- | ---
/sec/ign/link-owner | cmd line | any | boolean value, allows to skip the check whether or not the owner of a symbolic link is the owner of the link target
/sec/ign/dir-group-writable | cmd line | any | boolean value, allows to skip the check whether or not a symbolic link resides in a group-writable directory
/sec/ign/dir-world-writable | cmd line | any | boolean value, allows to skip the check whether or not a symbolic link resides in a group-writable or world-writable directory

#### Random number generation

Name | Source | Programs | Contents
--- | --- | --- | ---
/openssl/allow-random-seed-file | system | createp | boolean value, indicates whether or not a file may be used to seed the OpenSSL PRNG. This can be used to deny using random seed files for users having their home directories on NFS file systems. The default "on" allows the use of random seed files if this preference is not set.
/openssl/random-seed-file | any | createp rndbytes | name of the random seed file
/openssl/egd-socket | any | createp rndbytes | name of an EGD socket which can be used to seed the OpenSSL PRNG.

### Macros in preferences

The "/log/file/name", "/dir/app", "/dir/shared" and "/dir/tmp" preferences can use macros (placeholders) in the definitions:

Macro | Meaning
--- | ---
$(app.name) | application name
$(user.name) | the users login name
$(user.home) | the users home directory
$(user.uid) | the users UID
$(user.gid) | the users GID
$(user.euid) | the users effective UID
$(user.egid) | the users effective GID
$(host.name) | the short host name (computer name)
$(host.domain) | the hosts DNS domain name
$(app.dir) | the application directory (can not be used to define "/dir/app")
$(shared.dir) | the shared directory (can not be used to define "/dir/shared" or "/dir/app")
$(temp.dir) | the temporary directory (can not be used to define "/dir/tmp", "/dir/shared" or "/dir/app")
$(process.pid) | the PID of the current process
$(process.ppid) | the PID of the parent process
$(process.pgid) | the process group ID

Example:

    "/dir/app"="/usr/local/share/$(app.name)"
    "/log/file/name"="$(temp.dir)/$(app.name).$(process.pid).log"

### Examples

#### Unix/Linux examples

- If you are living in Germany and your computers do not use UTF-8 encoding set the preferred language for all users by adding the following section to ${sysconfdir}/appdefaults:

      [*]
      /ui/lang/env	= off
      /ui/lang	= de_DE

- The myapp1 application is available in English only, no support for German is available. So add the following section to ${sysconfdir}/appdefaults.myapp1:

      [*]
      /ui/lang	= en_US

- If you have a guest user (login name tadeusz) from Poland, add the following section to ${sysconfdir}/appdefaults:

      [tadeusz]
      /ui/lang	= pl

      [tadeusz/myapp1/*]
      /ui/lang	= en_US

- A guest user (login name pedro) comes from Spain. He is not mentioned in ${sysconfdir}/appdefaults yet, he can help himself by adding a section

      [*]
      /ui/lang	= sp

      [myapp1/*]
      /ui/lang	= en_US

  to his $HOME/.defaults/all file

#### Windows examples

- To set up German language for the majority of users add the entries

      "/ui/lang"="de_DE"
      "/ui/lang/env"="off"

  to the HKLM\Software\DkApp key.
- For myapp1 - an application available in English only - create an entry

      "/ui/lang"="en_US"

  in the HKLM\Software\DkApp\myapp1 key.
- For user Tadeusz (login name: tadeusz) from Poland add an entry

      "tadeusz:/ui/lang"="pl"

  to HKLM\Software\DkApp
  and an entry

      "tadeusz:/ui/lang"="en_US"

  to HKLM\Software\DkApp\myapp1.
  Alternatively add an entry

      "tadeusz/myapp1:/ui/lang"="en_US"

  to HKLM\Software\DkApp.
- User Pedro (login name: pedro) from Spain solves the language problem himself, he adds an entry

      "/ui/lang"="sp"

  to HKCU\Software\DkApp
  and an entry

      "/ui/lang"="en_US"

  to HKCU\Software\DkApp\myapp1.