Stores trace templates.
The trcrpt command, which formats trace reports, uses trace templates to determine how the data contained in trace entries should be formatted. All trace templates are stored in the master template file, /etc/trcfmt. Trace templates identify the trace hook ID, the version and release number, the indentation level, the event label, and data description fields. The data description fields contain formatting information for the trace entry data and can be repeated as many times as is necessary to format all of the trace data in the trace entry.
Modifying this File
The trcfmt file should only be modified using the trcupdate command. Trace hooks with values less than 010 are for internal use by the trace facilities. If these hooks are changed, the performance of trace, in particular trcrpt, is unpredictable.
The organization of the hook word depends on whether the application that produces the hook word is a 32-bit application or a 64-bit application.
32-bit trace hook words:
Item | Description |
---|---|
HookWord | The first two bytes of a HookWord contain the HookID and HookType. The contents of the second two bytes depends on the value of the HookType. |
HookID | The HookID is represented in the trace entry as 3 hexadecimal digits. For user programs, the hook id may be a value ranging from 0x010 to 0x0FF. HookIDs are defined in the /usr/include/sys/trchkid.h file. |
HookType | The HookType is a 4-bit value that identifies the
format of the remainder of the trace entry. You specify the HookType when you record the trace entry.
|
64-bit trace hook words:
Item | Description |
---|---|
HookWord | The first two bytes of a HookWord contain internal trace meta-data. The second two bytes contain the size of the trace entry minus the hook word and any internal data (such as timestamps or CPU ID). The third two bytes contain the hook ID that can use the full two bytes. A 12-bit hook ID valid in a 32-bit application of the form 0xhhh is equivalent to the 16-bit hook ID 0xhhh0 in a 64-bit application. The last two bytes represent the sub-hook ID. |
HookID | The HookID is represented in the trace entry as three or four hexadecimal digits. Four-digit hook IDs are valid only in AIX® 6.1 and later releases. For releases earlier than AIX 6.1, the hook ID can be a value ranging from 0x010 to 0xFFF. For user programs in AIX 6.1 and later releases, the hook ID can be a value ranging from 0x0100 to 0xFFFF. However, if the first hexadecimal digit is zero, the last digit must also be zero. For example, HookID 0AA0 is legal, but 0AAA is not. Many of the AIX system hook IDs are defined in the /usr/include/sys/trchkid.h file. |
Data Pointer
The DATA POINTER is a pointer to the current position in the trace entry. The DATA POINTER is changed by the trcrpt as it interprets the template and formats the trace entry. The initial position of the DATA POINTER is the third byte of the HookWord for HookTypes 1, 9, 2, A, 6, and E and the first byte after the HookWord for HookTypes 0 and 8.
Indentation Level
The formatted trace data is aligned in columns corresponding to the source of the trace event. This is identified in each template using the L=X descriptor. The possible values of the L=X command are as follows:
Item | Description |
---|---|
L=APPL | Outputs the trace data in the APPL (application) column. |
L=SVC | Outputs the trace data in the SVC (system call) column. |
L=KERN | Outputs the trace data in the KERN (kernel) column. |
L=INT | Outputs the trace data in the INT (interrupt)column. |
Continuation Character
A \ (backslash) at the end of a line must be used to continue a template on the next line.
Labels or Text Strings
Individual strings (or labels) can be separated by any number of spaces or tabs, but all excess spacing is compressed to one blank on the trace report unless other format structures are put into effect. Labels are enclosed in double quotes (" ").
Item | Description |
---|---|
\n | Outputs to a new line. Data on the new line is left-justified according to the value set in the INDENTATION LEVEL. |
\t | Inserts a tab. Tabs are expanded to spaces, using a fixed tabstop separation of 8. |
DATA POINTER Position Format Codes
Item | Description |
---|---|
Gm.n | Sets DATA POINTER to byte.bit location m.n. |
Om.n | Advances DATA POINTER by m.n byte.bits. |
Rm | Decrements DATA POINTER by m bytes. |
Output Format Codes
Item | Description |
---|---|
Bm.n | Sends output in Binary format where m is the length of the data in bytes and n is the length in bits. Unlike the other printing format codes, the DATA POINTER can be bit aligned and is not rounded up to the next byte boundary. |
D2, D4 , D8 | Converts data to signed decimal format. The length of the data is two, four, or eight bytes, and the DATA POINTER is advanced by the same number of bytes. |
F4 | Converts data to C type 'float' floating point format. The length of the data is 4 bytes, and the DATA POINTER is advanced by 4 bytes. |
F8 | Converts data to C type 'double' floating point format. The length of the data is 8 bytes, and the DATA POINTER is advanced by 8 bytes. |
S1, S2, S4 | Left-justifies ASCII strings. The length of the string is in the first byte (half-word, word) of the data. The length of the string does not include this byte. |
T4 | Outputs the next 4 bytes as a date and time string. |
U2, U4 , U8 | Converts data to unsigned decimal format. The length of the data is two, four, or eight bytes, and the DATA POINTER is advanced by the same number of bytes. |
Xm | Converts data to hexadecimal format. The DATA POINTER is advanced by m bytes. |
Interpreter Format Codes
Item | Description |
---|---|
E1, E2, E4 | Outputs the next byte (half_word, word) as an 'errno' value, replacing the numeric code with the corresponding #define name in the /usr/include/sys/errno.h file. The DATA POINTER is advanced by 1, 2, or 4 bytes. |
P4 | Uses the next word as a process ID, and outputs the pathname of the executable with that process ID. Process IDs and their pathnames are acquired by the trace command at the start of a trace and by the trcrpt command via a special EXEC tracehook. The DATA POINTER is advanced by 4 bytes. |
A SWITCH statement is a format code followed by a comma. Each CASE entry of the SWITCH statement consists of:
The switch is terminated by a CASE entry without a comma delimiter. The CASE entry is selected as the first entry whose MatchValue is equal to the expansion of the format code. The special matchvalue '\*' is a wildcard and matches anything.
The DATA POINTER is advanced by the format code.
Loops are used to output binary buffers of data; therefore, the descriptor for a LOOP is usually X0 or X1. The syntax of a loop is LOOP format_code {descriptor}. The descriptor is executed N times, where N is the numeric value of the format code.
The DATA POINTER is advanced by the format code and by the operations of the descriptor.
Macros are temporary variables that work like shell variables. They are assigned a value with the syntax:
{{ $xxx = EXPR }}
where EXPR is a combination of format codes, macros, and constants. The operators + (addition), - (subtraction), / (division), and * (multiplication). are permissible within macros.
Predefined Macros
Macro Name | Description |
---|---|
$BASEPOINTER | Marks the starting offset into an event. The default is 0, but the actual offset is the sum of the values of DATA POINTER and BASE_POINTER. It is used with template subroutines when the parts of an event have same structure and can be printed by same template but may have different starting points into an event. |
$BREAK | Ends the current trace event. |
$D1 - $D5 | Dataword 1 through dataword 5. The DATA POINTER is not moved. |
$DATAPOINTER | Activates the DATA POINTER. It can be set and manipulated like other user macros. |
$DEFAULT | Uses the DEFAULT template 008. |
$ERROR | Outputs an error message to the report and exit from the template after the current descriptor is processed. The error message supplies the logfile, the logfile offset of the start of that event, and the trace ID. |
$EXECPATH | Outputs the pathname of the executable for the current process. |
$HB | Number of bytes in trcgen subroutine variable length buffer. This is also equal to the 16-bit hook data. |
$HD | Hook data (lower 16 bits). |
$HT | Allows for multiple, different trchook subroutine
call with the same template. The return values of the $HT macro
are:
The DATA POINTER is not changed. |
$L1-$L2 | Long (64-bit) dataword 1, or 2. For example, $L1 is the concatination of $d1 and $d2. The 64-bit values would most likely have been traced with the TRCHK64L1 or TRCHK64L2 macros. No change to data pointer. |
$LOGID0 | Current logfile offset at the start of the event. |
$LOGIDX | Current logfile offset into this event. |
$LOGFILE | Returns the name of the logfile being processed. |
$MCR0, $MCR1, $MCRA | Machine MCR registers 0, 1, and A. |
$PID | Outputs the current process ID. |
$PMC1 - $PMC8 | Machine PMC registers 1 through 8. |
$PURR | Machine PURR register. |
$RELLINENO | Line number for this event. The first line starts at 1. |
$SKIP | Ends the current trace event without printing. |
$STOP | Immediately ends a trace report. |
$SVC | Outputs the name of the current system call. |
$TID | Outputs the current kernel thread ID. |
$TRACEID | Returns the trace ID of the current event. |
Built-in Macros
The built-in macros are:
Item | Description |
---|---|
buftofilename (bp) | Looks up filename by buf struct. |
fdinstall ( ) | Installs the file descriptor and the current v-node from lookuppn as a file_descriptor/v-node pair for this process ID. |
fdtofilename ( ) | Looks up the filename for the given file descriptor for this process ID. If the filename is not found, nothing is output. |
flih ( ) | Advances the Interrupt Depth. |
lookuppninstall1 | Installs the filename as the current file with the trcrpt command. |
lookuppninstall2 | Install the v-node as the current v-node. It also installs the current_v-node/current_file as a v-node/filename par. |
pfsrdwrinstall1 (vp) | Sets the current v-node of this process to vp. |
pfsrdwrinstall2 (VA.S, count) | Creates a virtual address/v-node structure to be filled in be VMM hooks if a page fault occurs. |
resume ( ) | Decrements the Interrupt Depth. |
setdelim ( ) | Inhibits spaces between characters. |
slihlookup ( ) | Looks up the second level interrupt handler. |
sidtofilename (sid) | Looks up filename by segment ID. |
vmbufinstall ( ) | Looks up the v-node of the file through the virtual page/sid and install the v-node and buf as a v-node/bp pair. This will be used by lvm on down. |
v-nodetofilename (vp) | Looks up filenames by v-node. |
vpagetofilename (vpage, sid) | Looks up filenames by vpage and segment ID. |
Item | Description |
---|---|
/etc/trcfmt | Stores trace templates. |
/usr/include/sys/trchkid.h | Defines hook identifiers. |
/usr/include/sys/trcmacros.h | Defines trace macros. |