POSIX_TRACE_EVENT(3P)

✨ POSIX_TRACE_EVENT(3P) ✨

okay bestie, pull up a chair because we're reading the POSIX Programmer's Manual together and honestly? it's giving niche but iconic. this page lives in the POSIX Programmer's Manual section 3P, and heads up before we even start: 💅

the Linux implementation of this interface may differ (so go check the corresponding Linux manual page for the actual Linux tea), or the interface might not even be implemented on Linux at all. 💀

---

🎀 PROLOG 🎀

this page is part of the POSIX Programmer's Manual. that's it, that's the prolog. the Linux version of this interface may differ, and it may not be implemented on Linux — so consult the Linux manual page for the real details, iykyk.

---

🌸 NAME 🌸

posix_trace_event, posix_trace_eventid_open — trace functions for instrumenting application code (TRACING). yes bestie, we're doing tracing, we're putting little spy cameras in your app code. 🕵️♀️✨

---

🦋 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 in the trace stream that the calling process is being traced into, and in which event_id is not filtered out. 🌈

now here's the vibe check on size: 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, then the truncation-status attribute of the trace event recorded is POSIX_TRACE_NOT_TRUNCATED. but if it is bigger, the user trace event data gets truncated down to that declared maximum size, and the truncation-status attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD. 😭 (the data got clipped, she's doing her best)

and posix_trace_event() shall have no effect — like, nothing, zero, nada — if:

• there is no trace stream created for the process, or
• the created trace stream is not running, or
• the trace event specified by event_id is filtered out in the trace stream.

moving on to her sister function: 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. she's got a max 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 you can define for any given process is limited by the maximum value {TRACE_USER_EVENT_MAX}, which has the minimum value {POSIX_TRACE_USER_EVENT_MAX}. so many limits, so little time. 🙈

🫶 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 gets returned in the variable pointed to by the event_id argument. if that user trace event name has already been mapped for the traced process, then the previously assigned trace event type identifier shall be returned (no duplicates, we don't do that here). 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 (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 gets returned in the variable pointed to by the event_id argument. if that 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. (main character consistency, honestly 👑)

oh and if there's no trace stream created, posix_trace_eventid_open() shall store this information for future trace streams created for this process. saving it for later, bestie. 💾

---

🔥 RETURN VALUE 🔥

No return value is defined for the posix_trace_event() function. she simply does not return, periodt.

upon successful completion, posix_trace_eventid_open() shall return a value of zero. otherwise, it shall return the corresponding error number. and if it's successful, 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}. ma'am your name is too long, the system said no. 😭

the following sections are informative. (just info, not rules, bestie)

---

🎀 EXAMPLES 🎀

None. that's it. nothing. empty. the void. 💀✨

---

🌸 APPLICATION USAGE 🌸

None. again. nothing here. 🫶

---

🦋 RATIONALE 🦋

None. she gave us nothing to work with and honestly? respect. 🙈

---

💜 FUTURE DIRECTIONS 💜

the posix_trace_event() and posix_trace_eventid_open() functions may be removed in a future version. ⚠️ yes bestie, they might get deprecated and sent to the shadow realm, so plan accordingly. not dramatic, just facts.

---

🌈 SEE ALSO 🌈

• Table 2-7, Trace Option: User Trace Event
• exec
• posix_trace_eventid_equal()
• posix_trace_start()
• 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!! 💖 brought to you by IEEE/The Open Group, 2017 — that's the source and the date, right at the bottom where she belongs. go forth and instrument your code, you absolute legend. 🧚✨