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
11

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

104       None.
105

APPLICATION USAGE

107       None.
108

RATIONALE

110       None.
111

FUTURE DIRECTIONS

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

SEE ALSO

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