trc_read 子例程

在线编辑

用途

从跟踪日志对象中读取。

库

libtrace.a

语法

#include <sys/libtrace.h>

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

描述

读取的 trc_read 子例程从其句柄包含在 处理 参数中的跟踪日志对象中读取下一个顺序数据项。 如果 读取的 trc_read 子例程跟随 trc_find_first 或 trc_find_next 调用，那么它将在找到的顺序数据项后读取下一个顺序数据项。 要读取与该条件匹配的下一个项，请使用 trc_find_next 子例程。 如果 处理 标志字段同时包含 TRC_MULTI_MERGE 和 TRC_REMOVE_DUPS，那么 读取的 trc_read 子例程将使用可能来自其他跟踪源的当前事件的任何重复条目。 所使用的条目数将在 trchi_dupcount 或 trcri_dupcount 变量中返回 (取决于分别是已处理的数据项还是已请求的原始数据项) ，如 "参数" 部分中所述。

参数

项 描述
句柄 (handle) 包含从对 trc_open 子例程的成功调用返回的句柄。
雷 指向 trc_read_t 结构以包含所返回的信息。 原始数据的格式将与今天在 特尔茨尔普特 内部数据缓冲区中对原始数据的格式设置相同。 在针对 32 位和 64 位事件的 /etc/trcfmt 文件中对此进行了描述。 因此， 32 位跟踪项将格式化为 32 位跟踪项，而不管它们是来自 32 位跟踪还是 64 位跟踪。 如果指定了 逐字记录 (TRC_LOG逐字记录) ，那么将完全按照跟踪的方式返回数据。

处理的数据是跟踪模板处理的结果，请参阅 /etc/trcfmt 文件。

应该使用 trc_Free 子例程来释放从 trc_read_t 数据类型引用的数据。 如果在打开对象时指定了 TRC_LOGLIVE 标志，那么不需要使用 trc_Free 子例程。

/usr/include/sys/libtrace.h 文件包含所返回数据的数据定义。
以下是对 trc_read_t 结构的定义。 它们被分成三个部分:
  • 原始数据项和已处理数据项的定义
  • 仅原始数据项的定义
  • 仅已处理数据项的定义
标号 数据类型 描述
trcr_magic INT 跟踪读取数据幻数。 这由库维护，以标识正在使用的库版本。
trcr_flags INT 用于描述返回的数据的标志。
以下为原始数据项的定义:
标号 数据类型 描述
trcri_hookid trc_hookid_t 如果跟踪条目来自 32 位源，那么挂钩标识的格式为 0x0hhh，其中 hhh 是 3-hex-位挂钩标识值 (例如， 134)。 如果跟踪条目来自 64 位源代码，在AIX® 6.1 之前，钩子 ID 的形式为 0x0hhh。 从 AIX 6.1开始， 16 位挂钩标识可用于 64 位源。 格式为 0xhhh0 (例如， 0x1340) 的 16 位挂钩标识表示为 0x0hhh (0x0134) ，而格式为 0xhhhh 的 16 位挂钩标识的值为 0xhhhh。
trcri_subhookid trc_subhookid_t 子挂钩标识。
trcri_cpuid unsigned CPU 标识 (如果已知)。 如果设置了 TRCRF_CPULUTYO 标志，那么可以确定 CPU 标识值，否则应该忽略此标志。
trcri_tid unsigned long long 线程标识。
trcri_timestamp unsigned long long 指定时间戳记 (以刻度标记为单位)。 使用 trc_ticks2nanos 函数将此值转换为纳秒。
trcri_rawofst unsigned long long 跟踪日志文件中此跟踪项的起始位置的偏移量。
trcri_rawlen INT 跟踪到的原始数据的长度。 这并不一定是用于日志文件中的数据的空间量。
trcri_rawbuf 字符 * 指向原始数据的指针。
trcri_component 字符 * 当前组件名称。 仅当处理组件跟踪日志文件时才有效。
trcri_logfile 字符 * 当前文件名。
trcri_dupcount INT 此 读取的 trc_read 调用使用的事件数。
TRC_LONGD1 (r) - TRC_LONGD5 (r) 返回由非通用跟踪挂钩跟踪的 5 数据字。 R 值的类型为 trc_read_t *，并且必须指向 trc_read_t 项。 这些宏返回未签名的 64 位值。
注: 这些宏不会进行检查以确保已跟踪指定的寄存器。
以下是已处理数据项的定义:
标号 数据类型 描述
trchi_hookid trc_hookid_t 如果跟踪条目来自 32 位源，那么挂钩标识的格式为 0x0hhh，其中 hhh 是 3-十六进制数字挂钩标识值 (例如， 134)。 如果跟踪条目来自 64 位源，那么挂钩标识的格式在 AIX 6.1之前为 0x0hhh 。 从 AIX 6.1开始， 16 位挂钩标识可用于 64 位源。 格式为 0xhhh0 (例如， 0x1340) 的 16 位挂钩标识表示为 0x0hhh (0x0134) ，而格式为 0xhhhh 的 16 位挂钩标识的值为 0xhhhh。
trchi_subhookid trc_subhookid_t 子挂钩标识。
trchi_elapsed_nseconds unsigned long long 从跟踪开始以来经过的时间 (以纳秒为单位)。
trchi_tid unsigned long long 线程标识。
trchi_pid unsigned long long 进程标识。
trchi_svc unsigned long long 系统呼叫地址。
特尔基拉沃夫斯特 unsigned long long 日志文件中跟踪事件的偏移量。
trchi_trcontime time64_t 最后一个 TRCON的时间，或此 TRCON。
trchi_trcofftime time64_t 最后一个 TRCOFF的时间，或此 TRCOFF。
trchi_cpuid INT CPU 标识。
trchi_rcpu INT 此跟踪中剩余的 CPU 数。
trchi_pri INT 进程优先级。
trchi_intr_depth INT 中断深度。
trchi_indent INT 特尔茨尔普特使用的缩进级别。 值为-1-$NOPRINT，0 - 无缩进，1 - 应用程序级，2 - SVC 级，3 - 内核级。 大于零的项指定在 ascii 数据的每一行之前的制表符的数目 (减 1) ，请参阅 特尔基 _ascii 字段。 每个选项卡都表示 8 空白，因此 trchi_indent = 2 表示 2-1 ，或 1 选项卡在每行数据之前，或 8 空白。
trchi_svcname 字符 * 当前 svc 名称。
trchi_procname 字符 * 当前进程名称。
trchi_filename 字符 * 当前文件名。
特尔基 _ascii 字符 * 这是此挂钩的跟踪模板所生成的数据。 根据 trchi_indent 值以及文本偏移量和后续行偏移量，每个数据行都以空格缩进，请参阅 trc_libcntl 子例程。
trchi_component 字符 * 当前组件名称。 仅当处理组件跟踪日志文件时才有效。
trchi_logfile 字符 * 当前文件名。
trchi_dupcount INT 此 读取的 trc_read 调用使用的事件数。
trcr_flags 字段包含描述所返回数据的特征的位标志。 值有：
项 描述
TRCRF_RAW 已读取原始数据， (例如) 已使用 TRC_LOGRAW 打开类型打开日志对象。 使用返回数据中的原始数据项 (例如，以 trcri_开头的原始数据项)。
TRCRF_PROC 读取了已处理的数据，例如，以 TRC_LOGPROC 打开类型打开了日志对象。 使用返回数据中的已处理数据项 (例如，以 trchi_开头的数据项)。
TRCRF_64BIT 该数据来自于 64 位环境。 请注意，跟踪本身可能来自 32 位或 64 位内核。
TRCRF_TIMESTAMPED 跟踪时，条目已添加时间戳记。
TRCRF_CPULUTYO cpu 标识是已知的。 如果 cpuid 包含在每个跟踪挂钩中 (请参阅 -p 跟踪 命令选项) ，或者跟踪是一个多 CPU 跟踪 (请参阅 -C 跟踪选项) ，那么将始终为已处理的条目设置此值。 对于已处理的跟踪，如果未跟踪相应的挂钩 (106 和 10C) ，那么 cpu 标识可能不准确。
TRCRF_GENERIC 这是一个通用跟踪条目，它是使用 RCGEN 或 TRCGENT 宏跟踪的条目。 这仅针对原始跟踪进行设置。
TRCRF_64BITTRACE 这是 64 位跟踪 (例如) ，它是使用 64 位内核进行的。
TRCRF_LIVEDATA 数据是实时的，不要将其释放。 当完成另一个读操作时，将更改数据。
TRCRF_NOPRINT 关联的跟踪模板指定了 $NOPRINT 或 $SKIP， (例如) 不应打印任何数据。

返回值

成功完成后， 读取的 trc_read 子例程将返回 0 ，并将数据放入 雷 区域。

错误代码

发生错误时， trc_read 子例程将 errno 全局变量设置为 errno.h中的值，并返回 errno.h 文件中的值或 libtrace.h 文件中定义的错误。
项 描述
EINVAL 句柄无效。
TRCE_BADFORMAT 跟踪数据的格式不正确，并且 错误号 全局变量设置为 EINVAL。