POSIX_T...XT_EVENT(3POSIX)

🌸 POSIX_T...XT_EVENT(3POSIX) — the trace-event-getter girlies 💅

okay so bestie, welcome to the POSIX Programmer's Manual ✨ quick vibe check before we dive in:

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

so like… your Linux box might be doing its own thing, or might not have this at all. no cap, read the Linux page if it exists. 🙈

---

✨ NAME ✨

posix_trace_getnext_event, posix_trace_timedgetnext_event, posix_trace_trygetnext_event — retrieve a trace event (TRACING) 🦋

---

🎀 SYNOPSIS 🎀

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

int posix_trace_getnext_event(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);
int posix_trace_timedgetnext_event(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 abstime);
int posix_trace_trygetnext_event(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);

three whole functions, three whole vibes, one shared mission 💖

---

🌈 DESCRIPTION 🌈

so posix_trace_getnext_event() shall report a recorded trace event — either from an active trace stream without log or from a pre-recorded trace stream, whichever one the trid argument is pointing at. meanwhile posix_trace_trygetnext_event() shall report a recorded trace event from an active trace stream without log identified by the trid argument. that's it. that's the assignment. 💅

the trace event info associated with the recorded trace event shall be copied by the function into the structure pointed to by the argument event, and the data associated with the trace event shall be copied into the buffer pointed to by the data argument. ✨

posix_trace_getnext_event() shall block if the trid argument identifies an active trace stream and there is currently no trace event ready to be retrieved. 😴 the way it just waits for you. when returning, if a recorded trace event was reported, the variable pointed to by the unavailable argument shall be set to zero. otherwise, the variable pointed to by the unavailable argument shall be set to a value different from zero. periodt.

posix_trace_timedgetnext_event() shall attempt to get another trace event from an active trace stream without log, exactly like posix_trace_getnext_event() does. but — and here's the plot twist 🫢 — if no trace event is available from the trace stream, the implied wait shall be terminated when the timeout specified by the argument abstime expires, and the function shall return the error [ETIMEDOUT].

the timeout shall expire when the absolute time specified by abstime passes, as measured by the clock upon which timeouts are based (that is, when the value of that clock equals or exceeds abstime), or if the absolute time specified by abstime has already passed at the time of the call. yeah she checks whether you're already late. iconic.

the timeout shall be based on the CLOCK_REALTIME clock. the resolution of the timeout shall be the resolution of the clock on which it is based. the timespec data type is defined in the <time.h> header. 🕰️

under no circumstance shall the function fail with a timeout if a trace event is immediately available from the trace stream. the validity of the abstime argument need not be checked if a trace event is immediately available from the trace stream. like, if the event's already there, we're not even gonna look at your timeout. 💀

the behavior of this function for a pre-recorded trace stream is unspecified. so don't. 🙈

posix_trace_trygetnext_event() shall not block. she's got places to be. this function shall return an error if the trid argument identifies a pre-recorded trace stream. if a recorded trace event was reported, the variable pointed to by the unavailable argument shall be set to zero. otherwise, if no trace event was reported, the variable pointed to by the unavailable argument shall be set to a value different from zero.

okay now the buffer math, stay with me bestie, this part is lowkey important 🧮

the argument num_bytes shall be the size of the buffer pointed to by the data argument. the argument data_len reports to the application the length in bytes of the data record just transferred. if num_bytes is greater than or equal to the size of the data associated with the trace event pointed to by the event argument, all the recorded data shall be transferred. in this case, the truncation-status member of the trace event structure shall be either:

• POSIX_TRACE_NOT_TRUNCATED, if the trace event data was recorded without truncation while tracing, or
• POSIX_TRACE_TRUNCATED_RECORD, if the trace event data was truncated when it was recorded.

if the num_bytes argument is less than the length of recorded trace event data, the data transferred shall be truncated to a length of num_bytes, the value stored in the variable pointed to by data_len shall be equal to num_bytes, and the truncation-status member of the event structure argument shall be set to POSIX_TRACE_TRUNCATED_READ (see the posix_trace_event_info structure defined in <trace.h>). 😭 she chopped it and she's telling you she chopped it.

the report of a trace event shall be sequential, starting from the oldest recorded trace event. trace events shall be reported in the order in which they were generated, up to an implementation-defined time resolution that causes the ordering of trace events occurring very close to each other to be unknown. so like, mostly in order, but if two events happened at basically the same time, nobody knows which one's first. 🦋

once reported, a trace event cannot be reported again from an active trace stream. no take-backs, no re-reads, she's moved on. 💅 and once a trace event is reported from an active trace stream without log, the trace stream shall make the resources associated with that trace event available to record future generated trace events. recycling queen ♻️✨

---

👑 RETURN VALUE 👑

upon successful completion, these functions shall return a value of zero. otherwise, they shall return the corresponding error number.

if successful, these functions store:

1. the recorded trace event in the object pointed to by event
2. the trace event information associated with the recorded trace event in the object pointed to by data
3. the length of this trace event information in the object pointed to by data_len
4. the value of zero in the object pointed to by unavailable

---

💀 ERRORS 💀

these functions shall fail if:

• EINVAL — the trace stream identifier argument trid is invalid. 🚫

the posix_trace_getnext_event() and posix_trace_timedgetnext_event() functions shall fail if:

• EINTR — the operation was interrupted by a signal, and so the call had no effect. 😭 rude of that signal honestly.

the posix_trace_trygetnext_event() function shall fail if:

• EINVAL — the trace stream identifier argument trid does not correspond to an active trace stream. (remember, no pre-recorded streams for this one!)

the posix_trace_timedgetnext_event() function shall fail if:

• EINVAL — there is no trace event immediately available from the trace stream, and the timeout argument is invalid.
• ETIMEDOUT — no trace event was available from the trace stream before the specified timeout timeout expired. ⏰ she waited, bestie. she waited and nothing came.

the following sections are informative. (so like, cute bonus content, not rules 💖)

---

🌸 EXAMPLES 🌸

None.

---

🦋 APPLICATION USAGE 🦋

None.

---

🧚 RATIONALE 🧚

None.

---

⭐ FUTURE DIRECTIONS ⭐

these functions may be removed in a future version. 😭 so like… enjoy them while they last, i guess.

---

🫶 SEE ALSO 🫶

• posix_trace_close()
• posix_trace_create()

The Base Definitions volume of POSIX.1‐2017, <sys_types.h>, <trace.h> 📚

---

💜 COPYRIGHT 💜

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html . 🔗

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html . 🐛

---

okay bestie that's the whole page, every last flag, error and footnote, no cap. 💖✨ this one came to you courtesy of IEEE/The Open Group, 2017 — stay traced, stay iconic, and don't forget to close your streams. byeeee 👑🎀🦋