oasis-root

posix_trace_getnext_event.3p (8442B)

'\" et
.TH POSIX_TRACE_GETNEXT_EVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
posix_trace_getnext_event,
posix_trace_timedgetnext_event,
posix_trace_trygetnext_event
\(em retrieve a trace event
(\fBTRACING\fP)
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <trace.h>
.P
int posix_trace_getnext_event(trace_id_t \fItrid\fP,
    struct posix_trace_event_info *restrict \fIevent\fP,
    void *restrict \fIdata\fP, size_t \fInum_bytes\fP,
    size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP);
int posix_trace_timedgetnext_event(trace_id_t \fItrid\fP,
    struct posix_trace_event_info *restrict \fIevent\fP,
    void *restrict \fIdata\fP, size_t \fInum_bytes\fP,
    size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP,
    const struct timespec *restrict \fIabstime\fP);
int posix_trace_trygetnext_event(trace_id_t \fItrid\fP,
    struct posix_trace_event_info *restrict \fIevent\fP,
    void *restrict \fIdata\fP, size_t \fInum_bytes\fP,
    size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP);
.fi
.SH DESCRIPTION
The
\fIposix_trace_getnext_event\fR()
function shall report a recorded trace event either from an
active trace stream without log
or a pre-recorded trace stream identified by the
.IR trid
argument.
The
\fIposix_trace_trygetnext_event\fR()
function shall report a recorded trace event from an active
trace stream without log identified by the
.IR trid
argument.
.P
The trace event information associated with the recorded trace event
shall be copied by the function into the structure pointed to by the
argument
.IR event
and the data associated with the trace event shall be copied into the
buffer pointed to by the
.IR data
argument.
.P
The
\fIposix_trace_getnext_event\fR()
function shall block if the
.IR trid
argument identifies an active trace stream and there is currently no
trace event ready to be retrieved. When returning, if a recorded trace
event was reported, the variable pointed to by the
.IR unavailable
argument shall be set to zero. Otherwise, the variable pointed to by
the
.IR unavailable
argument shall be set to a value different from zero.
.P
The
\fIposix_trace_timedgetnext_event\fR()
function shall attempt to get another trace event from an active trace
stream without log, as in the
\fIposix_trace_getnext_event\fR()
function. However, if no trace event is available from the trace
stream, the implied wait shall be terminated when the timeout specified
by the argument
.IR abstime
expires, and the function shall return the error
.BR [ETIMEDOUT] .
.P
The timeout shall expire when the absolute time specified by
.IR abstime
passes, as measured by the clock upon which timeouts are based (that
is, when the value of that clock equals or exceeds
.IR abstime ),
or if the absolute time specified by
.IR abstime
has already passed at the time of the call.
.P
The timeout shall be based on the CLOCK_REALTIME clock.
The resolution of the timeout shall be the resolution of the clock
on which it is based. The
.BR timespec
data type is defined in the
.IR <time.h> 
header.
.P
Under no circumstance shall the function fail with a timeout if a trace
event is immediately available from the trace stream. The validity of
the
.IR abstime
argument need not be checked if a trace event is immediately available
from the trace stream.
.P
The behavior of this function for a pre-recorded trace stream is
unspecified.
.P
The
\fIposix_trace_trygetnext_event\fR()
function shall not block.
This function shall return an error if the
.IR trid
argument identifies a pre-recorded trace stream.
If a recorded trace event was reported, the variable pointed to by the
.IR unavailable
argument shall be set to zero. Otherwise, if no trace event was
reported, the variable pointed to by the
.IR unavailable
argument shall be set to a value different from zero.
.P
The argument
.IR num_bytes
shall be the size of the buffer pointed to by the
.IR data
argument. The argument
.IR data_len
reports to the application the length in bytes of the data record just
transferred. If
.IR num_bytes
is greater than or equal to the size of the data associated with the
trace event pointed to by the
.IR event
argument, all the recorded data shall be transferred. In this case,
the
.IR truncation-status
member of the trace event structure shall be either
POSIX_TRACE_NOT_TRUNCATED,
if the trace event data was recorded without truncation while tracing,
or POSIX_TRACE_TRUNCATED_RECORD,
if the trace event data was truncated when it was recorded. If the
.IR num_bytes
argument is less than the length of recorded trace event data, the data
transferred shall be truncated to a length of
.IR num_bytes ,
the value stored in the variable pointed to by
.IR data_len
shall be equal to
.IR num_bytes ,
and the
.IR truncation-status
member of the
.IR event
structure argument shall be set to POSIX_TRACE_TRUNCATED_READ
(see the
.BR posix_trace_event_info
structure defined in
.IR <trace.h> ).
.P
The report of a trace event shall be sequential starting from the
oldest recorded trace event. Trace events shall be reported in the
order in which they were generated, up to an implementation-defined
time resolution that causes the ordering of trace events occurring very
close to each other to be unknown. Once reported, a trace event cannot
be reported again from an active trace stream. Once a trace event is
reported from an active trace stream without log, the trace stream
shall make the resources associated with that trace event available to
record future generated trace events.
.SH "RETURN VALUE"
Upon successful completion, these functions shall return a value of
zero. Otherwise, they shall return the corresponding error number.
.P
If successful, these functions store:
.IP " *" 4
The recorded trace event in the object pointed to by
.IR event
.IP " *" 4
The trace event information associated with the recorded trace event in
the object pointed to by
.IR data
.IP " *" 4
The length of this trace event information in the object pointed to by
.IR data_len
.IP " *" 4
The value of zero in the object pointed to by
.IR unavailable
.SH ERRORS
These functions shall fail if:
.TP
.BR EINVAL
The trace stream identifier argument
.IR trid
is invalid.
.P
The
\fIposix_trace_getnext_event\fR()
and
\fIposix_trace_timedgetnext_event\fR()
functions shall fail if:
.TP
.BR EINTR
The operation was interrupted by a signal, and so the call had no
effect.
.P
The
\fIposix_trace_trygetnext_event\fR()
function shall fail if:
.TP
.BR EINVAL
The trace stream identifier argument
.IR trid
does not correspond to an active trace stream.
.br
.P
The
\fIposix_trace_timedgetnext_event\fR()
function shall fail if:
.TP
.BR EINVAL
There is no trace event immediately available from the trace stream,
and the
.IR timeout
argument is invalid.
.TP
.BR ETIMEDOUT
No trace event was available from the trace stream before the specified
timeout
.IR timeout
expired.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
None.
.SH "FUTURE DIRECTIONS"
These functions may be removed in a future version.
.SH "SEE ALSO"
.IR "\fIposix_trace_close\fR\^(\|)",
.IR "\fIposix_trace_create\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_types.h>\fP",
.IR "\fB<trace.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .