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 *restrictdata_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
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 Trace Option:  User  Trace  Event  )
60       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 ( Trace Option: User Trace Event  )  user
72       trace event shall be returned.
73
74       Note:  The  above  procedure, together with the fact that multiple pro‐
75              cesses can only be traced into the same trace stream by  inheri‐
76              tance,  ensure  that  all  the  processes that are traced into a
77              trace stream have the same mapping of trace event names to trace
78              event type identifiers.
79
80
81       If  there  is  no  trace stream created, the posix_trace_eventid_open()
82       function shall store this information for future trace streams  created
83       for this process.
84

RETURN VALUE

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

ERRORS

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

EXAMPLES

106       None.
107

APPLICATION USAGE

109       None.
110

RATIONALE

112       None.
113

FUTURE DIRECTIONS

115       None.
116

SEE ALSO

118       Trace     Option:     User     Trace     Event,    posix_trace_start(),
119       posix_trace_trid_eventid_open(),  the  Base   Definitions   volume   of
120       IEEE Std 1003.1-2001, <sys/types.h>, <trace.h>
121
123       Portions  of  this text are reprinted and reproduced in electronic form
124       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
125       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
126       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
127       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
128       event of any discrepancy between this version and the original IEEE and
129       The  Open Group Standard, the original IEEE and The Open Group Standard
130       is the referee document. The original Standard can be  obtained  online
131       at http://www.opengroup.org/unix/online.html .
132
133
134
135IEEE/The Open Group                  2003                POSIX_TRACE_EVENT(3P)
Impressum