POSIX_TRA...NEXT_EVENT(3P)

💅 POSIX_TRA...NEXT_EVENT(3P) 💅

okay so bestie, this page is from the POSIX Programmer's Manual, and the title up there is the manual name (yes it's got that cute little ... in the middle, that's just how it is, don't question it 🫶).

🚨 PROLOG

This manual page is part of the POSIX Programmer's Manual. Heads up though, fr fr: the Linux implementation of this interface may differ (so go check the corresponding Linux manual page for the tea ☕), or the interface might not even be implemented on Linux at all. Not me being dramatic, that's literally what it says 💀.

---

✨ NAME ✨

posix_trace_getnext_event, posix_trace_timedgetnext_event, posix_trace_trygetnext_event — retrieve a trace event (TRACING). That's the whole vibe: you want a trace event, these three girlies will get it for you 👑

---

📜 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);

---

🌸 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 points at. And posix_trace_trygetnext_event() shall report a recorded trace event from an active trace stream without log identified by the trid argument. That's the distinction, and it matters, ok? 💅

The trace event information attached to that recorded trace event gets copied by the function into the structure that event points to, and the data attached to the trace event gets copied into the buffer that data points to. Copy copy copy, she's thorough 💖.

Now, posix_trace_getnext_event() shall block if trid identifies an active trace stream and there's currently no trace event ready to be retrieved. Like she'll just wait there, patiently, main character energy. When she returns, if a recorded trace event was reported, the variable pointed to by unavailable shall be set to zero. Otherwise — no event for you — that variable gets set to a value different from zero.

Then there's posix_trace_timedgetnext_event(), which shall attempt to get another trace event from an active trace stream without log, same as posix_trace_getnext_event() does. BUT — if no trace event is available from the trace stream, that implied wait shall be terminated when the timeout specified by the abstime argument expires, and the function shall return the error [ETIMEDOUT]. She's got places to be 💅.

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, past-tense timeout, she's already late.

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's based. And the timespec data type is defined in the <time.h> header, just so you know where she lives 🎀.

Under no circumstance shall the function fail with a timeout if a trace event is immediately available from the trace stream. And the validity of the abstime argument need not be checked if a trace event is immediately available from the trace stream. Basically if the event's already there, we are NOT checking your homework, we're just handing it over 🫶.

The behavior of this function for a pre-recorded trace stream is unspecified. No cap, unspecified is unspecified, don't come for me.

posix_trace_trygetnext_event() shall not block. She does not wait, she does not linger, she checks and she goes. 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 unavailable shall be set to zero. Otherwise, if no trace event was reported, the variable pointed to by unavailable shall be set to a value different from zero.

Okay now the num_bytes / data_len situation, pay attention bestie:

• num_bytes shall be the size of the buffer pointed to by the data 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 event, then all the recorded data shall be transferred. In that 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, then 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 (peep the posix_trace_event_info structure defined in <trace.h> for the full fit check).

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 basically, super close events, their order is a mystery, we don't know her 🌫️. Once reported, a trace event cannot be reported again from an active trace stream. 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 era ♻️✨.

---

💖 RETURN VALUE 💖

Upon successful completion, these functions shall return a value of zero. Otherwise, they shall return the corresponding error number. Simple. Clean. Iconic.

If successful, these functions store:

• The recorded trace event in the object pointed to by event
• The trace event information associated with the recorded trace event in the object pointed to by data
• The length of this trace event information in the object pointed to by data_len
• 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.

The posix_trace_trygetnext_event() function shall fail if:

• EINVAL — The trace stream identifier argument trid does not correspond to an active trace stream.

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 expired.

The following sections are informative. (Yes girl, informative, not normative — we're just chatting 💅)

---

🌈 EXAMPLES 🌈

None. Bestie there are literally none, that's the whole entry 😭.

---

🦋 APPLICATION USAGE 🦋

None. Also none. The audacity, honestly 🙈.

---

🧚 RATIONALE 🧚

None. Nothing here either. She's giving minimalist ✨.

---

🔮 FUTURE DIRECTIONS 🔮

These functions may be removed in a future version. Not saying she's on the way out but like... she might not be at the function reunion, iykyk 💀.

---

👑 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 .

---

And that's the whole page, bestie — courtesy of IEEE/The Open Group, dated 2017, from the POSIX Programmer's Manual. Stay traced, stay iconic, and remember: she might block, but she'll never ghost you 💜✨