1POSIX_TRACE_GETNEXT_EVENT(3PP)OSIX Programmer's ManuPaOlSIX_TRACE_GETNEXT_EVENT(3P)
2
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
12 posix_trace_getnext_event, posix_trace_timedgetnext_event,
13 posix_trace_trygetnext_event - retrieve a trace event (TRACING)
14
16 #include <sys/types.h>
17 #include <trace.h>
18 int posix_trace_getnext_event(trace_id_t trid,
20 struct posix_trace_event_info *restrict event,
21 void *restrict data, size_t num_bytes,
22 size_t *restrict data_len, int *restrict unavailable);
23 int posix_trace_timedgetnext_event(trace_id_t trid,
26 struct posix_trace_event_info *restrict event,
27 void *restrict data, size_t num_bytes,
28 size_t *restrict data_len, int *restrict unavailable,
29 const struct timespec *restrict abs_timeout);
30 int posix_trace_trygetnext_event(trace_id_t trid,
33 struct posix_trace_event_info *restrict event,
34 void *restrict data, size_t num_bytes,
35 size_t *restrict data_len, int *restrict unavailable);
36
39 The posix_trace_getnext_event() function shall report a recorded trace
40 event either from an active trace stream without log or a pre-recorded
41 trace stream identified by the trid argument. The posix_trace_tryget‐
42 next_event() function shall report a recorded trace event from an
43 active trace stream without log identified by the trid argument.
44 The trace event information associated with the recorded trace event
46 shall be copied by the function into the structure pointed to by the
47 argument event and the data associated with the trace event shall be
48 copied into the buffer pointed to by the data argument.
49 The posix_trace_getnext_event() function shall block if the trid argu‐
51 ment identifies an active trace stream and there is currently no trace
52 event ready to be retrieved. When returning, if a recorded trace event
53 was reported, the variable pointed to by the unavailable argument shall
54 be set to zero. Otherwise, the variable pointed to by the unavailable
55 argument shall be set to a value different from zero.
56 The posix_trace_timedgetnext_event() function shall attempt to get
58 another trace event from an active trace stream without log, as in the
59 posix_trace_getnext_event() function. However, if no trace event is
60 available from the trace stream, the implied wait shall be terminated
61 when the timeout specified by the argument abs_timeout expires, and the
62 function shall return the error [ETIMEDOUT].
63 The timeout shall expire when the absolute time specified by abs_time‐
65 out passes, as measured by the clock upon which timeouts are based
66 (that is, when the value of that clock equals or exceeds abs_timeout),
67 or if the absolute time specified by abs_timeout has already passed at
68 the time of the call.
69 If the Timers option is supported, the timeout shall be based on the
71 CLOCK_REALTIME clock; if the Timers option is not supported, the time‐
72 out shall be based on the system clock as returned by the time() func‐
73 tion. The resolution of the timeout shall be the resolution of the
74 clock on which it is based. The timespec data type is defined in the
75 <time.h> header.
76 Under no circumstance shall the function fail with a timeout if a trace
78 event is immediately available from the trace stream. The validity of
79 the abs_timeout argument need not be checked if a trace event is imme‐
80 diately available from the trace stream.
81 The behavior of this function for a pre-recorded trace stream is
83 unspecified.
84 The posix_trace_trygetnext_event() function shall not block. This
86 function shall return an error if the trid argument identifies a pre-
87 recorded trace stream. If a recorded trace event was reported, the
88 variable pointed to by the unavailable argument shall be set to zero.
89 Otherwise, if no trace event was reported, the variable pointed to by
90 the unavailable argument shall be set to a value different from zero.
91 The argument num_bytes shall be the size of the buffer pointed to by
93 the data argument. The argument data_len reports to the application the
94 length in bytes of the data record just transferred. If num_bytes is
95 greater than or equal to the size of the data associated with the trace
96 event pointed to by the event argument, all the recorded data shall be
97 transferred. In this case, the truncation-status member of the trace
98 event structure shall be either POSIX_TRACE_NOT_TRUNCATED, if the trace
99 event data was recorded without truncation while tracing, or
100 POSIX_TRACE_TRUNCATED_RECORD, if the trace event data was truncated
101 when it was recorded. If the num_bytes argument is less than the length
102 of recorded trace event data, the data transferred shall be truncated
103 to a length of num_bytes, the value stored in the variable pointed to
104 by data_len shall be equal to num_bytes, and the truncation-status mem‐
105 ber of the event structure argument shall be set to POSIX_TRACE_TRUN‐
106 CATED_READ (see the posix_trace_event_info structure defined in
107 <trace.h>).
108 The report of a trace event shall be sequential starting from the old‐
110 est recorded trace event. Trace events shall be reported in the order
111 in which they were generated, up to an implementation-defined time res‐
112 olution that causes the ordering of trace events occurring very close
113 to each other to be unknown. Once reported, a trace event cannot be
114 reported again from an active trace stream. Once a trace event is
115 reported from an active trace stream without log, the trace stream
116 shall make the resources associated with that trace event available to
117 record future generated trace events.
118
120 Upon successful completion, these functions shall return a value of
121 zero. Otherwise, they shall return the corresponding error number.
122 If successful, these functions store:
124 * The recorded trace event in the object pointed to by event
126 * The trace event information associated with the recorded trace event
128 in the object pointed to by data
129 * The length of this trace event information in the object pointed to
131 by data_len
132 * The value of zero in the object pointed to by unavailable
134
136 These functions shall fail if:
137 EINVAL The trace stream identifier argument trid is invalid.
139 The posix_trace_getnext_event() and posix_trace_timedgetnext_event()
142 functions shall fail if:
143 EINTR The operation was interrupted by a signal, and so the call had
145 no effect.
146 The posix_trace_trygetnext_event() function shall fail if:
149 EINVAL The trace stream identifier argument trid does not correspond to
151 an active trace stream.
152 The posix_trace_timedgetnext_event() function shall fail if:
155 EINVAL There is no trace event immediately available from the trace
157 stream, and the timeout argument is invalid.
158 ETIMEDOUT
160 No trace event was available from the trace stream before the
161 specified timeout timeout expired.
162 The following sections are informative.
165
167 None.
168
170 None.
171
173 None.
174
176 None.
177
179 posix_trace_create(), posix_trace_open(), the Base Definitions volume
180 of IEEE Std 1003.1-2001, <sys/types.h>, <trace.h>
181
183 Portions of this text are reprinted and reproduced in electronic form
184 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
185 -- Portable Operating System Interface (POSIX), The Open Group Base
186 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
187 Electrical and Electronics Engineers, Inc and The Open Group. In the
188 event of any discrepancy between this version and the original IEEE and
189 The Open Group Standard, the original IEEE and The Open Group Standard
190 is the referee document. The original Standard can be obtained online
191 at http://www.opengroup.org/unix/online.html .
192IEEE/The Open Group 2003 POSIX_TRACE_GETNEXT_EVENT(3P)