1POSIX_TRACE_EVENT(3P)      POSIX Programmer's Manual     POSIX_TRACE_EVENT(3P)
2
3
4

PROLOG

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

NAME

12       posix_trace_event,  posix_trace_eventid_open  —  trace  functions   for
13       instrumenting application code (TRACING)
14

SYNOPSIS

16       #include <sys/types.h>
17       #include <trace.h>
18
19       void posix_trace_event(trace_event_id_t event_id,
20           const void *restrict data_ptr, size_t data_len);
21       int posix_trace_eventid_open(const char *restrict event_name,
22           trace_event_id_t *restrict event_id);
23

DESCRIPTION

25       The posix_trace_event() function shall record the event_id and the user
26       data pointed to by data_ptr in the trace stream into which the  calling
27       process  is  being traced and in which event_id is not filtered out. If
28       the total size of the user trace event data represented by data_len  is
29       not  greater  than the declared maximum size for user trace event data,
30       then the truncation-status attribute of the  trace  event  recorded  is
31       POSIX_TRACE_NOT_TRUNCATED.   Otherwise,  the  user  trace event data is
32       truncated to this  declared  maximum  size  and  the  truncation-status
33       attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD.
34
35       If  there  is no trace stream created for the process or if the created
36       trace stream is not  running,  or  if  the  trace  event  specified  by
37       event_id  is  filtered out in the trace stream, the posix_trace_event()
38       function shall have no effect.
39
40       The posix_trace_eventid_open() function shall associate  a  user  trace
41       event  name with a trace event type identifier for the calling process.
42       The trace  event  name  is  the  string  pointed  to  by  the  argument
43       event_name.   It shall have a maximum of {TRACE_EVENT_NAME_MAX} charac‐
44       ters (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}).   The
45       number of user trace event type identifiers that can be defined for any
46       given process is limited by the maximum  value  {TRACE_USER_EVENT_MAX},
47       which has the minimum value {POSIX_TRACE_USER_EVENT_MAX}.
48
49       If  the  Trace  Inherit  option is not supported, the posix_trace_even‐
50       tid_open() function shall associate the user trace event  name  pointed
51       to  by  the event_name argument with a trace event type identifier that
52       is unique for the traced process,  and  is  returned  in  the  variable
53       pointed  to  by the event_id argument. If the user trace event name has
54       already been  mapped  for  the  traced  process,  then  the  previously
55       assigned  trace  event  type  identifier shall be returned. If the per-
56       process    user    trace    event    name    limit    represented    by
57       {TRACE_USER_EVENT_MAX}    has    been    reached,    the    pre-defined
58       POSIX_TRACE_UNNAMED_USEREVENT (see Table 2-7, Trace Option: User  Trace
59       Event) user trace event shall be returned.
60
61       If  the  Trace  Inherit  option  is  supported,  the  posix_trace_even‐
62       tid_open() function shall associate the user trace event  name  pointed
63       to  by  the event_name argument with a trace event type identifier that
64       is unique for all the processes being traced in this same trace stream,
65       and is returned in the variable pointed to by the event_id argument. If
66       the user trace event name has already been mapped for the  traced  pro‐
67       cesses,  then the previously assigned trace event type identifier shall
68       be returned. If the per-process user trace event name limit represented
69       by   {TRACE_USER_EVENT_MAX}   has   been   reached,   the   pre-defined
70       POSIX_TRACE_UNNAMED_USEREVENT (Table  2-7,  Trace  Option:  User  Trace
71       Event) user trace event shall be returned.
72
73       Note:     The  above  procedure,  together  with the fact that multiple
74                 processes can only be traced into the same  trace  stream  by
75                 inheritance,  ensure  that  all the processes that are traced
76                 into a trace stream have the  same  mapping  of  trace  event
77                 names to trace event type identifiers.
78
79       If  there  is  no  trace stream created, the posix_trace_eventid_open()
80       function shall store this information for future trace streams  created
81       for this process.
82

RETURN VALUE

84       No return value is defined for the posix_trace_event() function.
85
86       Upon  successful  completion,  the  posix_trace_eventid_open() function
87       shall return a value of zero. Otherwise, it  shall  return  the  corre‐
88       sponding  error  number. The posix_trace_eventid_open() function stores
89       the trace event type identifier value  in  the  object  pointed  to  by
90       event_id, if successful.
91

ERRORS

93       The posix_trace_eventid_open() function shall fail if:
94
95       ENAMETOOLONG
96              The  size  of the name pointed to by the event_name argument was
97              longer      than      the      implementation-defined      value
98              {TRACE_EVENT_NAME_MAX}.
99
100       The following sections are informative.
101

EXAMPLES

103       None.
104

APPLICATION USAGE

106       None.
107

RATIONALE

109       None.
110

FUTURE DIRECTIONS

112       The posix_trace_event() and posix_trace_eventid_open() functions may be
113       removed in a future version.
114

SEE ALSO

116       Table 2-7, Trace Option:  User  Trace  Event,  exec,  posix_trace_even‐
117       tid_equal(), posix_trace_start()
118
119       The Base Definitions volume of POSIX.1‐2017, <sys_types.h>, <trace.h>
120
122       Portions  of  this text are reprinted and reproduced in electronic form
123       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
124       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
125       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
126       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
127       event of any discrepancy between this version and the original IEEE and
128       The  Open Group Standard, the original IEEE and The Open Group Standard
129       is the referee document. The original Standard can be  obtained  online
130       at http://www.opengroup.org/unix/online.html .
131
132       Any  typographical  or  formatting  errors that appear in this page are
133       most likely to have been introduced during the conversion of the source
134       files  to  man page format. To report such errors, see https://www.ker
135       nel.org/doc/man-pages/reporting_bugs.html .
136
137
138
139IEEE/The Open Group                  2017                POSIX_TRACE_EVENT(3P)
Impressum