POSIX_TRACE_EVENT(3POSIX)

🌸 POSIX_TRACE_EVENT(3POSIX) 🌸

okay bestie, welcome to the POSIX Programmer's Manual 💖 this one's POSIX_TRACE_EVENT(3POSIX) and it's all about tracing your app's lil moments. buckle up 🎀

---

⚠️ PROLOG ⚠️

ngl, real talk first: this page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ — so like, consult the corresponding Linux manual page for the deets on Linux behavior 🙈 — or honestly the interface may just not be implemented on Linux at all. vibe check: check before you commit 💀

---

✨ NAME ✨

posix_trace_event, posix_trace_eventid_open — trace functions for instrumenting application code (TRACING) 🦋

---

🎀 SYNOPSIS 🎀

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

void posix_trace_event(trace_event_id_t event_id,
    const void *restrict data_ptr, size_t data_len);
int posix_trace_eventid_open(const char *restrict event_name,
    trace_event_id_t *restrict event_id);

---

💅 DESCRIPTION 💅

so posix_trace_event() shall record the event_id and the user data pointed to by data_ptr into the trace stream that the calling process is being traced into — but only in the streams where event_id is not filtered out 👑. and here's the tea on truncation, bestie:

• if the total size of the user trace event data represented by data_len is not greater than the declared maximum size for user trace event data → the truncation-status attribute of the trace event recorded is POSIX_TRACE_NOT_TRUNCATED ✨
• otherwise → the user trace event data gets truncated to that declared maximum size, and the truncation-status attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD 😭 (she got cut off)

also, if there's no trace stream created for the process, or if the created trace stream is not running, or if the trace event specified by event_id is filtered out in the trace stream — then posix_trace_event() shall have no effect. literally nothing happens. it's giving ghosted 💀

---

now posix_trace_eventid_open() shall associate a user trace event name with a trace event type identifier for the calling process 🫶. the trace event name is the string pointed to by the argument event_name. it shall have a maximum of {TRACE_EVENT_NAME_MAX} characters (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}) 📏. and the number of user trace event type identifiers that can be defined for any given process is limited by the maximum value {TRACE_USER_EVENT_MAX}, which has the minimum value {POSIX_TRACE_USER_EVENT_MAX} 🔢.

if the Trace Inherit option is NOT supported 🙅: posix_trace_eventid_open() shall associate the user trace event name pointed to by the event_name argument with a trace event type identifier that is unique for the traced process, and it's returned in the variable pointed to by the event_id argument. if the user trace event name has already been mapped for the traced process, then the previously assigned trace event type identifier shall be returned (same name, same id, periodt 💅). but if the per-process user trace event name limit represented by {TRACE_USER_EVENT_MAX} has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see Table 2-7, Trace Option: User Trace Event) user trace event shall be returned 🌈.

if the Trace Inherit option IS supported ✅: posix_trace_eventid_open() shall associate the user trace event name pointed to by the event_name argument with a trace event type identifier that is unique for all the processes being traced in this same trace stream, and it's returned in the variable pointed to by the event_id argument 👑. if the user trace event name has already been mapped for the traced processes, then the previously assigned trace event type identifier shall be returned. and if the per-process user trace event name limit represented by {TRACE_USER_EVENT_MAX} has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (Table 2-7, Trace Option: User Trace Event) user trace event shall be returned 🌸.

Note: the above procedure, together with the fact that multiple processes can only be traced into the same trace stream by inheritance, ensure that all the processes that are traced into a trace stream have the same mapping of trace event names to trace event type identifiers 🧚 — iconic, honestly, consistency is the moment.

and if there is no trace stream created, posix_trace_eventid_open() shall store this information for future trace streams created for this process 📝 (manifesting for later, bestie).

---

⭐ RETURN VALUE ⭐

no return value is defined for the posix_trace_event() function 🙈 — she returns nothing, she just vibes.

upon successful completion, posix_trace_eventid_open() shall return a value of zero 🎉. otherwise, it shall return the corresponding error number 😭. and on success, posix_trace_eventid_open() stores the trace event type identifier value in the object pointed to by event_id ✨.

---

🔥 ERRORS 🔥

posix_trace_eventid_open() shall fail if:

• ENAMETOOLONG — the size of the name pointed to by the event_name argument was longer than the implementation-defined value {TRACE_EVENT_NAME_MAX} 😵 too much name, babe.

the following sections are informative 👀 (iykyk, they're the bonus content).

---

🦋 EXAMPLES 🦋

None. — yeah bestie, the examples section is empty. we have nothing. zero. nada 🙈

---

💜 APPLICATION USAGE 💜

None. — also empty. no tips, no tricks, no life hacks. moving on 🫶

---

🌈 RATIONALE 🌈

None. — no reasoning given. she simply exists. main character energy 👑

---

🕰️ FUTURE DIRECTIONS 🕰️

the posix_trace_event() and posix_trace_eventid_open() functions may be removed in a future version 💀 so like, enjoy them while they last, bestie.

---

👀 SEE ALSO 👀

• Table 2-7, Trace Option: User Trace Event
• exec
• posix_trace_eventid_equal()
• posix_trace_start()

and from 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 💖✨ this was brought to you by IEEE/The Open Group, 2017, and the manual POSIX_TRACE_EVENT(3POSIX) — stay traced, stay iconic 🎀🦋👑