posix_trace_timedgetnext_event 子例程

用途

检索跟踪事件。

语法

#include <sys/types.h>
#include <trace.h>

int posix_trace_timedgetnext_event
(trid, event, data, num_bytes, data_len, unavailable, abs_timeout)
trace_id_t trid;
struct posix_trace_event_info *restrict event;
void *restrict data;
size_t num_bytes;
size_t *restrict data_len;
int *restrict unavailable;
const struct timespec *restrict abs_timeout;

描述

posix_trace_timedgetnext_event 子例程尝试从没有日志的活动跟踪流中获取另一个跟踪事件，如 posix_trace_getnext_event 子例程中所示。 但是，如果跟踪流中没有可用的跟踪事件，那么当参数 abs_timeout 指定的超时到期时，隐式等待将终止，并且该函数将返回错误 [ETIMEDOUT]。

当 abs_timeout 指定的绝对时间过去或在调用时已经过去时，超时将到期。 abs_timeout 指定的绝对时间由超时所基于的时钟度量 (即，当该时钟的值等于或超过 abs_timeout时)。

超时基于 CLOCK_REALTIME 时钟。 超时的解析是 CLOCK_REALTIME 的解析。 timespec 数据类型在 time.h 头文件中定义。

如果跟踪事件在跟踪流中立即可用，那么该函数永远不会因超时而失败。 如果跟踪事件在跟踪流中立即可用，那么不会检查 abs_timeout 参数的有效性。

未指定预先记录的跟踪流的此子例程的行为。

num_bytes 参数等于 data 参数指向的缓冲区大小。 data_len 参数向应用程序报告刚刚传输的数据记录的长度 (以字节计)。 如果 num_bytes 大于或等于与 event 参数指向的跟踪事件关联的数据大小，那么将传输所有记录的数据。 在这种情况下，跟踪事件结构的 truncation-status 成员为 POSIX_TRACE_NOT_TRUNC( 如果跟踪时记录跟踪事件数据未截断) 或 POSIX_TRACE_TRUNCATED_RECORD (如果记录跟踪事件数据时截断)。 如果 num_bytes 参数小于记录的跟踪事件数据的长度，那么传输的数据将截断为 num_bytes 参数的长度， data_len 指向的变量中存储的值等于 num_bytes，并且 event 结构参数的 truncation-status 成员将设置为 POSIX_TRACE_TRUNCATED_READ (请参阅posix_trace_event_infotrace.h中定义的结构。

跟踪事件的报告是从最早记录的跟踪事件开始顺序的。 按生成跟踪事件的顺序报告跟踪事件，直到实现定义的时间解析导致跟踪事件的顺序彼此非常接近而未知。 报告后，无法从活动跟踪流再次报告跟踪事件。 从没有日志的活动跟踪流报告跟踪事件后，跟踪流会使与该跟踪事件相关联的资源可用于记录将来生成的跟踪事件。

参数

返回值

成功完成时， posix_trace_timedgetnext_event 子例程返回值 0。 否则，将返回相应的错误号。

如果成功， posix_trace_timedgetnext_event 子例程存储:

• event 指向的对象中记录的跟踪事件
• 与 data 指向的对象中记录的跟踪事件相关联的跟踪事件信息
• data_len 指向的对象中此跟踪事件信息的长度
• unavailable 指向的对象中 0 的值

错误代码

如果返回以下错误代码，那么 posix_trace_timedgetnext_event 子例程将失败:

文件

文件参考中的pthread.h、trace.h和types.h。