Reads from a trace log object.
libtrace.a
#include <sys/libtrace.h>
int trc_read (handle, ret)
trc_log_handle_t handle;
trc_read_t *ret;
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.
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. |
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. |
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. |
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. |
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. |
Upon successful completion, the trc_read subroutine returns a 0 and puts the data into the ret area.
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. |