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.
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 data recorded for each traced event consist of a word containing the trace hook identifier and the hook type followed by a variable number of words of trace data optionally followed by a timestamp. The word containing the trace hook identifier and the hook type is call the hook word. The remaining two bytes of the hook word are called hook data and are available for recording event data.
| 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.
|
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.
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:
| 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. |
A \ (backslash) at the end of a line must be used to continue a template on the next line.
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 (" ").
| \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. |
| 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. |
| 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. |
| 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.
The built-in macros are:
| 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. |
| /etc/trcfmt | Stores trace templates. |
| /usr/include/sys/trchkid.h | Defines hook identifiers. |
| /usr/include/sys/trcmacros.h | Defines trace macros. |
The trcupdate command.
The trcgen subroutine, trchook subroutine.
Trace Facility Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.