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
13 posix_trace_getnext_event, posix_trace_timedgetnext_event,
14 posix_trace_trygetnext_event — retrieve a trace event (TRACING)
15
17 #include <sys/types.h>
18 #include <trace.h>
19 int posix_trace_getnext_event(trace_id_t trid,
21 struct posix_trace_event_info *restrict event,
22 void *restrict data, size_t num_bytes,
23 size_t *restrict data_len, int *restrict unavailable);
24 int posix_trace_timedgetnext_event(trace_id_t trid,
25 struct posix_trace_event_info *restrict event,
26 void *restrict data, size_t num_bytes,
27 size_t *restrict data_len, int *restrict unavailable,
28 const struct timespec *restrict abstime);
29 int posix_trace_trygetnext_event(trace_id_t trid,
30 struct posix_trace_event_info *restrict event,
31 void *restrict data, size_t num_bytes,
32 size_t *restrict data_len, int *restrict unavailable);
33
35 The posix_trace_getnext_event() function shall report a recorded trace
36 event either from an active trace stream without log or a pre-recorded
37 trace stream identified by the trid argument. The posix_trace_tryget‐
38 next_event() function shall report a recorded trace event from an
39 active trace stream without log identified by the trid argument.
40 The trace event information associated with the recorded trace event
42 shall be copied by the function into the structure pointed to by the
43 argument event and the data associated with the trace event shall be
44 copied into the buffer pointed to by the data argument.
45 The posix_trace_getnext_event() function shall block if the trid argu‐
47 ment identifies an active trace stream and there is currently no trace
48 event ready to be retrieved. When returning, if a recorded trace event
49 was reported, the variable pointed to by the unavailable argument shall
50 be set to zero. Otherwise, the variable pointed to by the unavailable
51 argument shall be set to a value different from zero.
52 The posix_trace_timedgetnext_event() function shall attempt to get
54 another trace event from an active trace stream without log, as in the
55 posix_trace_getnext_event() function. However, if no trace event is
56 available from the trace stream, the implied wait shall be terminated
57 when the timeout specified by the argument abstime expires, and the
58 function shall return the error [ETIMEDOUT].
59 The timeout shall expire when the absolute time specified by abstime
61 passes, as measured by the clock upon which timeouts are based (that
62 is, when the value of that clock equals or exceeds abstime), or if the
63 absolute time specified by abstime has already passed at the time of
64 the call.
65 The timeout shall be based on the CLOCK_REALTIME clock. The resolution
67 of the timeout shall be the resolution of the clock on which it is
68 based. The timespec data type is defined in the <time.h> header.
69 Under no circumstance shall the function fail with a timeout if a trace
71 event is immediately available from the trace stream. The validity of
72 the abstime argument need not be checked if a trace event is immedi‐
73 ately available from the trace stream.
74 The behavior of this function for a pre-recorded trace stream is
76 unspecified.
77 The posix_trace_trygetnext_event() function shall not block. This
79 function shall return an error if the trid argument identifies a pre-
80 recorded trace stream. If a recorded trace event was reported, the
81 variable pointed to by the unavailable argument shall be set to zero.
82 Otherwise, if no trace event was reported, the variable pointed to by
83 the unavailable argument shall be set to a value different from zero.
84 The argument num_bytes shall be the size of the buffer pointed to by
86 the data argument. The argument data_len reports to the application the
87 length in bytes of the data record just transferred. If num_bytes is
88 greater than or equal to the size of the data associated with the trace
89 event pointed to by the event argument, all the recorded data shall be
90 transferred. In this case, the truncation-status member of the trace
91 event structure shall be either POSIX_TRACE_NOT_TRUNCATED, if the trace
92 event data was recorded without truncation while tracing, or
93 POSIX_TRACE_TRUNCATED_RECORD, if the trace event data was truncated
94 when it was recorded. If the num_bytes argument is less than the length
95 of recorded trace event data, the data transferred shall be truncated
96 to a length of num_bytes, the value stored in the variable pointed to
97 by data_len shall be equal to num_bytes, and the truncation-status mem‐
98 ber of the event structure argument shall be set to POSIX_TRACE_TRUN‐
99 CATED_READ (see the posix_trace_event_info structure defined in
100 <trace.h>).
101 The report of a trace event shall be sequential starting from the old‐
103 est recorded trace event. Trace events shall be reported in the order
104 in which they were generated, up to an implementation-defined time res‐
105 olution that causes the ordering of trace events occurring very close
106 to each other to be unknown. Once reported, a trace event cannot be
107 reported again from an active trace stream. Once a trace event is
108 reported from an active trace stream without log, the trace stream
109 shall make the resources associated with that trace event available to
110 record future generated trace events.
111
113 Upon successful completion, these functions shall return a value of
114 zero. Otherwise, they shall return the corresponding error number.
115 If successful, these functions store:
117 * The recorded trace event in the object pointed to by event
119 * The trace event information associated with the recorded trace
121 event in the object pointed to by data
122 * The length of this trace event information in the object pointed to
124 by data_len
125 * The value of zero in the object pointed to by unavailable
127
129 These functions shall fail if:
130 EINVAL The trace stream identifier argument trid is invalid.
132 The posix_trace_getnext_event() and posix_trace_timedgetnext_event()
134 functions shall fail if:
135 EINTR The operation was interrupted by a signal, and so the call had
137 no effect.
138 The posix_trace_trygetnext_event() function shall fail if:
140 EINVAL The trace stream identifier argument trid does not correspond to
142 an active trace stream.
143 The posix_trace_timedgetnext_event() function shall fail if:
145 EINVAL There is no trace event immediately available from the trace
147 stream, and the timeout argument is invalid.
148 ETIMEDOUT
150 No trace event was available from the trace stream before the
151 specified timeout timeout expired.
152 The following sections are informative.
154
156 None.
157
159 None.
160
162 None.
163
165 These functions may be removed in a future version.
166
168 posix_trace_close(), posix_trace_create()
169 The Base Definitions volume of POSIX.1‐2008, <sys_types.h>, <trace.h>
171
173 Portions of this text are reprinted and reproduced in electronic form
174 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
175 -- Portable Operating System Interface (POSIX), The Open Group Base
176 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
177 cal and Electronics Engineers, Inc and The Open Group. (This is
178 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
179 event of any discrepancy between this version and the original IEEE and
180 The Open Group Standard, the original IEEE and The Open Group Standard
181 is the referee document. The original Standard can be obtained online
182 at http://www.unix.org/online.html .
183 Any typographical or formatting errors that appear in this page are
185 most likely to have been introduced during the conversion of the source
186 files to man page format. To report such errors, see https://www.ker‐
187 nel.org/doc/man-pages/reporting_bugs.html .
188IEEE/The Open Group 2013 POSIX_TRACE_GETNEXT_EVENT(3P)