Files Reference

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.

Trace Entries

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. Value Trace Entry Format 1 The trace entry consists of only the HookWord. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine. 2 The trace entry consists of the HookWord and one additional word of trace data. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine. 6 The trace entry consists of the HookWord and up to five additional words of trace data. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine. 8 The trace entry consists of the HookWord and a data word followed by a variable number of bytes of trace data and a timestamp. The third and fourth bytes of the HookWord contain the number of bytes of trace data which follows the trace word. Trace entries of this type are recorded using the trcgent subroutine or the trcgenkt kernel service. 9 The trace entry consists of the HookWord and a timestamp. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine. A The trace entry consists of the HookWord, one additional word of trace data, and a timestamp. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine. E The trace entry consists of the HookWord, up to five additional words of trace data, and a timestamp. The third and fourth bytes of the HookWord contain trace data. Trace entries of this type are recorded using the trchook or utrchook subroutine. 0 The trace entry consists of the HookWord and a data word followed by a variable number of bytes of trace data. The third and fourth bytes of the HookWord contain the number of bytes of trace data which follows the trace word. Trace entries of this type are recorded using the trcgen subroutine or the trcgenk kernel service.

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.

Trace Data Formatting

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:

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 (" ").

\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.

Format Codes

DATA POINTER Position Format Codes

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

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

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.

Switch Statements

A SWITCH statement is a format code followed by a comma. Each CASE entry of the SWITCH statement consists of:

A 'MatchValue' with a type (usually numeric) corresponding to the format code.
A simple 'String' or a new 'Descriptor' bounded by braces. A descriptor is a sequence of format codes, strings, switches, and loops.
A comma delimiter.

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.

LOOP Statements

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

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: Value Description 1 hook word 2 hook word and one additional word 6 hook word and up to five data words 9 hook word and a timestamp A hook word, one data word, and a timestamp E hook word, up to five data words, and a timestamp. 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.
$RELLINENO	Line number for this event. The first line starts at 1.
$PID	Outputs the current process ID.
$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:

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.

Implementation Specifics

The trcfmt file is part of the operating system.

Files

/etc/trcfmt	Stores trace templates.
/usr/include/sys/trchkid.h	Defines hook identifiers.
/usr/include/sys/trcmacros.h	Defines trace macros.

Related Information

The trcupdate command.

The trcgen subroutine, trchook subroutine.

Trace Facility Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.