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.

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.