Configuration

Kernel Trace for OS/2 provides a stanza-based, text, configuration file. This file, KTRACE.CFG, gives the user a simple means to modify the behavior of the program. Please refer to the File Listing section of this document to determine where this file must be located in order for Kernel Trace to find it and use the information it contains.

Editing KTRACE.CFG

Configurable options provided by the KTRACE.CFG file are:

The definition of tracepoint aliases for filtering, in connection with the -tTRACEPOINTS command line option to the control program.
The assignment of control program parameter defaults.

Sections

KTRACE.CFG is comprised of two sections: TRACEPOINTS and DEFAULTS. Both sections and their contents are described below. Any other sections found in this file will be ignored.

TRACEPOINTS

This section contains a key/value pair for each tracepoint alias. The following syntax rules apply to this section of the file:

A tracepoint alias value may refer only to a valid hexadecimal tracepoint identifier or to another alias key which has been defined before it in the file.
To avoid circular references, an alias value may not refer to any other alias key defined after it in the file.
A key with no value is invalid and will be ignored.
A value with no key is invalid and will be ignored.
Within the value portion, alias keys and hexadecimal tracepoint IDs may be bitwise ORed together in any combination using the plus symbol (+).
Leading zeros in hexadecimal tracepoint IDs may be omitted.
A line preceeded by a semi-colon (;) is treated as a comment and will be ignored.
Excess white space between keys and values will be ignored.
Alias key names may contain hexadecimal digits, but may not consist entirely of hexadecimal digits.
If multiple key names are identical (ignoring case and whitespace), only the last key name defined in the file will be used.

Base Tracepoint Identifiers
TRACEPOINT ALIAS	HEX VALUE	TRACEPOINT ALIAS	HEX VALUE
`OPEN_PRE`	`0000000001`	`FINDFIRSTS3X`	`0000020000`
`OPEN_POST`	`0000000002`	`FINDNEXT`	`0000040000`
`READ_PRE`	`0000000004`	`FINDFIRSTNEXT3X`	`0000080000`
`READ_POST`	`0000000008`	`FINDCLOSE`	`0000100000`
`WRITE_PRE`	`0000000010`	`FINDCLOSE3X`	`0000200000`
`WRITE_POST`	`0000000020`	`SETFILESIZE`	`0000400000`
`CLOSE`	`0000000040`	`QUERYFILEINFO`	`0000800000`
`CHGFILEPTR`	`0000000080`	`SETFILEINFO`	`0001000000`
`DELETE_PRE`	`0000000100`	`SETFILEMODE`	`0002000000`
`DELETE_POS`	`0000000200`	`SETPATHINFO`	`0004000000`
`MOVE_PRE`	`0000000400`	`MAKEDIR`	`0008000000`
`MOVE_POST`	`0000000800`	`CHANGEDIR`	`0010000000`
`LOADEROPEN`	`0000001000`	`REMOVEDIR`	`0020000000`
`GETMODULE`	`0000002000`	`CREATEVDM`	`0040000000`
`EXECPGM`	`0000004000`	`CREATEVDMPOST`	`0080000000`
`EXECPGMPOST`	`0000008000`	`SETDATETIME`	`0100000000`
`FINDFIRST`	`0000010000`	`DEVIOCTL`	`0200000000`
Aliases for Common Tracepoint Groupings These aliases have been created in the default `ktrace.cfg` file in order to group similar tracepoints together.
`ALL`	`03FFFFFFFF`
`OC`	`OPEN_POST+CLOSE`
`RW`	`READ_POST+WRITE_POST+CHGFILEPTR`
`FIND`	`FINDFIRST+FINDFIRST3X+FINDNEXT+FINDFIRSTNEXT3X+FINDCLOSE+FINDCLOSE3X`
`INFO`	`QUERYFILEINFO+SETFILEINFO+SETFILESIZE+SETFILEMODE+SETPATHINFO`
`X`	`EXECPGMPOST+LOADEROPEN+GETMODULE+CREATEVDMPOST`

DEFAULTS
This section allows the user to customize defaults for the program's command line arguments. Default values are specified as keyword/value pairs, using the syntax KEY = VALUE. The following syntax rules apply to this section of the file:

A key with no value is valid and indicates that the program's internal default value for that parameter will be used.
If a key/value pair is omitted altogether, the program's internal default value for that parameter will be used.
A value with no key is invalid and is ignored.
A line preceeded by a semi-colon (;) is treated as a comment and will be ignored.
Excess white space between keys and values will be ignored.

Note: Command line parameters take precedence over values defined in ktrace.cfg.


KEYWORD	Command Line Equivalent	DEFINITION
`FILENAME`	`-fFILENAME`	Default Trace Filename Note: filename extension must be `.ktr` - other extensions will be ignored.
`MAXSIZE`	`-mMAXSIZE`	Default maximum trace size in megabytes
`PIDLIST`	`-iPIDx`	Default list of process IDs to trace, separated by comma (`,`)
`PIDMASK`	`-pPIDMASK`	Default pattern of process names to trace
`FILEFILTER`	`-lFILEFILTER`	Default pattern of filenames to trace (file-related tracepoints only)
`TRACEPOINTS`	`-tTRACEPOINTS`	Default active tracepoints
`COMMENT`	`-cCOMMENT`	Default comment for trace files