trc_read Subroutine

Purpose

Reads from a trace log object.

Library

libtrace.a

Syntax

#include <sys/libtrace.h>

int trc_read (handle, ret)
trc_log_handle_t handle;
trc_read_t *ret;

Description

The trc_read subroutine reads the next sequential data item from the trace log object whose handle is contained in the handle parameter. If the trc_read subroutine follows a trc_find_first or trc_find_next call, it reads the next sequential data item after the one found. To read the next item matching that criteria, use the trc_find_next subroutine. If the handle flag field contains both TRC_MULTI_MERGE and TRC_REMOVE_DUPS, the trc_read subroutine consumes any duplicate entries of the current event that might exist from other trace sources. The number of entries consumed will be returned in the trchi_dupcount or trcri_dupcount variable (depending on whether processed or raw data items, respectively, are requested) described in the Parameters section.

Parameters

Item Description
handle Contains the handle returned from a successful call to the trc_open subroutine.
ret Points to the trc_read_t structure to contain the returned information. The raw data will be formatted the same way it is formatted today in the trcrpt internal data buffer. This is described in the /etc/trcfmt file for both 32 and 64 bit events. Thus 32-bit trace items will be formatted as 32-bit items regardless of whether they came from a 32 or 64 bit trace. If TRC_LOGVERBATIM was specified, data is returned exactly as traced.

Processed data is the result of trace template processing, see the /etc/trcfmt file.

The trc_free subroutine should be used to free data referenced from the trc_read_t data type. The trc_free subroutine need not be used if the TRC_LOGLIVE flag was specified when the object was opened.

The /usr/include/sys/libtrace.h file contains the data definitions for the returned data.

The following are definitions for the trc_read_t structure. They are split into three sections:
  • Definitions for both raw and processed data items
  • Definitions for raw data items only
  • Definitions for processed data items only
Label Data Type Description
trcr_magic int Trace read data magic number. This is maintained by the library to identify the library version in use.
trcr_flags int Flags that describe the data returned.
The following are definitions for raw data items:
Label Data Type Description
trcri_hookid trc_hookid_t If the trace entry comes from a 32-bit source, the hook ID is in the form of 0x0hhh, where hhh is a 3-hex-digit hook ID value (for example, 134). If the trace entry comes from a 64-bit source, the hook ID is in the form of 0x0hhh before AIX® 6.1. Beginning with AIX 6.1, 16-bit hook IDs are available for 64-bit sources. 16-bit hook IDs in the form of 0xhhh0 (for example, 0x1340) are represented as 0x0hhh (0x0134) while 16-bit hook IDs in the form of 0xhhhh have the value of 0xhhhh.
trcri_subhookid trc_subhookid_t Subhook ID.
trcri_cpuid unsigned The CPU ID if known. If the TRCRF_CPUIDOK flag is set, the CPU ID value could be determined, otherwise it should be ignored.
trcri_tid unsigned long long Thread ID.
trcri_timestamp unsigned long long Specifies the timestamp in ticks. Use the trc_ticks2nanos function to convert this value to nanoseconds.
trcri_rawofst unsigned long long The offset to the start of this trace item in the trace log file.
trcri_rawlen int The length of the raw data as traced. This is not necessarily the amount of space used for the data in the log file.
trcri_rawbuf char * Pointer to the raw data.
trcri_component char * Current component name. Valid only when processing a component trace log file.
trcri_logfile char * Current file name.
trcri_dupcount int Number of events consumed by this trc_read call.
TRC_LONGD1(r) - TRC_LONGD5(r) return the 5 data words traced by non-generic trace hooks. The r value is of type trc_read_t *, and must point to a trc_read_t item. These macros return unsigned, 64-bit values.
Note: These macros do not check to ensure that the specified register was traced.
The following are definitions for processed data items:
Label Data Type Description
trchi_hookid trc_hookid_t If the trace entry came from a 32-bit source, the hook ID is in the form of 0x0hhh, where hhh is a 3-hex-digit hook ID value (for example, 134). If the trace entry comes from a 64-bit source, the hook ID is in the form of 0x0hhh before AIX 6.1. Beginning with AIX 6.1, 16-bit hook IDs are available to 64-bit sources. 16-bit hook IDs in the form of 0xhhh0 (for example, 0x1340) are represented as 0x0hhh (0x0134) while 16-bit hook IDs in the form of 0xhhhh have the value of 0xhhhh.
trchi_subhookid trc_subhookid_t Subhook ID.
trchi_elapsed_nseconds unsigned long long The elapsed time from the start of the trace in nanoseconds.
trchi_tid unsigned long long Thread ID.
trchi_pid unsigned long long Process ID.
trchi_svc unsigned long long System call address.
trchi_rawofst unsigned long long Offset of the trace event in the log file.
trchi_trcontime time64_t The time of the last TRCON, or this TRCON.
trchi_trcofftime time64_t The time of the last TRCOFF, or this TRCOFF.
trchi_cpuid int CPU ID.
trchi_rcpu int CPUs remaining in this trace.
trchi_pri int Process priority.
trchi_intr_depth int Interrupt depth.
trchi_indent int The indentation level used by trcrpt. The values are -1 - $NOPRINT, 0 - no indentation, 1 - application level, 2 - SVC level, 3 - kernel level. Items greater than zero specify the number of tabs, minus 1, that precede each line of the ascii data, see the trchi_ascii field. Each tab represents 8 blanks, so trchi_indent = 2 implies 2 - 1, or 1 tab before each line of data, or 8 blanks.
trchi_svcname char * Current svc name.
trchi_procname char * Current process name.
trchi_filename char * Current file name.
trchi_ascii char * This is the data produced by the trace template for this hook. Each line of data is indented with blanks, according to the trchi_indent value, and the text offset and the subsequent line offset, see the trc_libcntl subroutine.
trchi_component char * Current component name. Valid only when processing a component trace log file.
trchi_logfile char * Current file name.
trchi_dupcount int Number of events consumed by this trc_read call.
The trcr_flags field contains bit flags describing characteristics of the returned data. The values are:
Item Description
TRCRF_RAW Raw data was read, (for example) the log object was opened with the TRC_LOGRAW open type. Use the raw data items in the return data, (for example) those beginning with trcri_.
TRCRF_PROC Processed data was read, (for example) the log object was opened with the TRC_LOGPROC open type. Use the processed data items in the return data, (for example) those beginning with trchi_.
TRCRF_64BIT The data is from a 64-bit environment. Note that the trace itself may be from a 32 or 64 bit kernel.
TRCRF_TIMESTAMPED The entry was timestamped when traced.
TRCRF_CPUIDOK The cpu id is known. This is always set for a processed entry, and set for a raw entry if the cpuid was contained in each trace hook (see the -p trace command option), or the trace is a multi-cpu trace (see the -C trace option). For a processed trace, the cpu id may not be accurate if the appropriate hooks, 106 and 10C, weren't traced.
TRCRF_GENERIC This is a generic trace entry, one traced with the TRCGEN or TRCGENT macros. This is set for a raw trace only.
TRCRF_64BITTRACE This is a 64-bit trace, (for example) it was taken with a 64-bit kernel.
TRCRF_LIVEDATA The data is live, don't free it. The data will be changed when another read operation is done.
TRCRF_NOPRINT The associated trace template specified $NOPRINT or $SKIP, (for example) no data should be printed.

Return Values

Upon successful completion, the trc_read subroutine returns a 0 and puts the data into the ret area.

Error Codes

Upon error, the trc_read subroutine sets the errno global variable to a value from errno.h, and returns either a value from the errno.h file or an error defined in the libtrace.h file.
Item Description
EINVAL The handle is not valid.
TRCE_BADFORMAT The trace data is improperly formatted, and the errno global variable is set to EINVAL.