trchook, utrchook, trchook64, and utrhook64 Subroutine

Purpose

Records a trace event.

Library

Runtime Services Library (librts.a)

Syntax

#include <sys/trchkid.h>

void trchook( HkWord, d1, d2, d3, d4, d5) unsigned int HkWord, d1, d2, d3, d4, d5;

void utrchook(HkWord, d1, d2, d3, d4, d5)
unsigned int HkWord, d1, d2, d3, d4, d5;

void trchook64 (HkWord, d1, d2, d3, d4, d5)
unsigned long HkWord, d1, d2, d3, d4, d5;

void utrchook64 (HkWord, d1, d2, d3, d4, d5)
unsigned long HkWord, d1, d2, d3, d4, d5;

Description

The trchook subroutine records a trace event if a trace session is active. Input parameters include a hook word (HkWord) and from 0 to 5 words of data. The trchook and trchook64 subroutines are intended for use by the kernel and extensions.

The utrchook and utrchook64 subroutines are intended for programs running at user (application) level.

The trchook and utrchook subroutines are for use in a 32-bit environment, while the trchook64 and utrchook64 subroutines are intended for use in a 64-bit environment. Note that if running a 64-bit application on a 32-bit kernel, the application should use utrchook64(the subroutine for its 64-bit environment).

It is strongly recommended that the C macros TRCHKLn and TRCHKLnT (where n is from 0 to 5) be used if possible, instead of calling these subroutines directly.

Beginning with AIX 5L™ Version 5.3 with the 5300-05 Technology Level, all events are implicitly appended with a time stamp.

Parameters

Item	Description
d1, d2, d3, d4, d5	Up to 5 words of data from the calling program.
HkWord	The HkWord parameter has a different format based upon the environment. For the trchook and utrchook subroutines, it is an unsigned long consisting of a hook ID (HkID), a hook type (Hk_Type), and two bytes of data from the calling program (HkData). HkID A hook ID is a 12-bit value. For user programs, the hook ID may be a value from 0x010 to 0x0FF. Hook identifiers are defined in the /usr/include/sys/trchkid.h file. Hk_Type A 4-bit value that identifies the amount of trace data to be recorded: Value Records 1 Hook word 9 Hook word and a time stamp 2 Hook word and one data word A Hook word, one data word, and a time stamp 6 Hook word and up to five data words E Hook word, up to five data words, and a time stamp. HkData Two bytes of data from the calling program.

Item

Description

d1, d2, d3, d4, d5

Up to 5 words of data from the calling program.

HkWord

The HkWord parameter has a different format based upon the environment. For the trchook and utrchook subroutines, it is an unsigned long consisting of a hook ID (HkID), a hook type (Hk_Type), and two bytes of data from the calling program (HkData).

HkID

A hook ID is a 12-bit value. For user programs, the hook ID may be a value from 0x010 to 0x0FF. Hook identifiers are defined in the /usr/include/sys/trchkid.h file.

Hk_Type

A 4-bit value that identifies the amount of trace data to be recorded:

Value: Records
1: Hook word
9: Hook word and a time stamp
2: Hook word and one data word
A: Hook word, one data word, and a time stamp
6: Hook word and up to five data words
E: Hook word, up to five data words, and a time stamp.
HkData: Two bytes of data from the calling program.

In a 64-bit environment, when the trchook64 or utrchook64 subroutine is used, the format is ffffllllhhhhssss, where f represents flags, l is length, h is the hook ID, and s is the subhook.

Beginning with AIX® 6.1, 16-bit hook IDs are available in the 64-bit environment. 16-bit hook IDs in the form of 0xhhh0 are equivalent to 12-bit hook IDs in the form of 0xhhh where h is a hexadecimal digit. When a hook ID is less than 0x1000, its least significant digit must be 0.

The hook and subhook ids are the same as for the 32-bit environment (12-bit hook id and a 16-bit subhook id). Note that the 4 bits between the hook id and subhook are unused.

The flags (the first 16 bits of the 64-bit hookword) are specified as follows:

8000: The hook should be timestamped.
4000: A generic trace entry, should not use the trchook64 or utrchook64 subroutine. For more information see trcgen or trcgent Subroutine.
2000: The hook contains 32-bit data. Used by aix trace only.
1000: Automatically include the cpuid when tracing the data.

The length (l) is the second 16 bits of the hookword. It is the length of the data. The length is 0 if no data other than the hookword is traced (TRCHKL0), 8 if one parameter, 8 bytes, is traced (TRCHKL1), 16 for 2 parameters, 24 for 3 parameters, 32 for 4 parameters, and 40 for 5 parameters (TRCHKL5).