Movatterモバイル変換

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.

SYNOPSIS top

#include <sys/types.h> #include <trace.h> int posix_trace_getnext_event(trace_id_ttrid, struct posix_trace_event_info *restrictevent, void *restrictdata, size_tnum_bytes, size_t *restrictdata_len, int *restrictunavailable); int posix_trace_timedgetnext_event(trace_id_ttrid, struct posix_trace_event_info *restrictevent, void *restrictdata, size_tnum_bytes, size_t *restrictdata_len, int *restrictunavailable, const struct timespec *restrictabstime); int posix_trace_trygetnext_event(trace_id_ttrid, struct posix_trace_event_info *restrictevent, void *restrictdata, size_tnum_bytes, size_t *restrictdata_len, int *restrictunavailable);

DESCRIPTION top

Theposix_trace_getnext_event() function shall report a recorded trace event either from an active trace stream without log or a pre-recorded trace stream identified by thetrid argument. Theposix_trace_trygetnext_event() function shall report a recorded trace event from an active trace stream without log identified by thetrid argument. The trace event information associated with the recorded trace event shall be copied by the function into the structure pointed to by the argumentevent and the data associated with the trace event shall be copied into the buffer pointed to by thedata argument. Theposix_trace_getnext_event() function shall block if thetrid 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 theunavailable argument shall be set to zero. Otherwise, the variable pointed to by theunavailable argument shall be set to a value different from zero. Theposix_trace_timedgetnext_event() function shall attempt to get another trace event from an active trace stream without log, as in theposix_trace_getnext_event() function. However, if no trace event is available from the trace stream, the implied wait shall be terminated when the timeout specified by the argumentabstime expires, and the function shall return the error[ETIMEDOUT]. The timeout shall expire when the absolute time specified byabstime passes, as measured by the clock upon which timeouts are based (that is, when the value of that clock equals or exceedsabstime), or if the absolute time specified byabstime has already passed at the time of the call. 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. Thetimespecdata type is defined in the<time.h> header. Under no circumstance shall the function fail with a timeout if a trace event is immediately available from the trace stream. The validity of theabstime argument need not be checked if a trace event is immediately available from the trace stream. The behavior of this function for a pre-recorded trace stream is unspecified. Theposix_trace_trygetnext_event() function shall not block. This function shall return an error if thetrid argument identifies a pre-recorded trace stream. If a recorded trace event was reported, the variable pointed to by theunavailable argument shall be set to zero. Otherwise, if no trace event was reported, the variable pointed to by theunavailable argument shall be set to a value different from zero. The argumentnum_bytes shall be the size of the buffer pointed to by thedata argument. The argumentdata_len reports to the application the length in bytes of the data record just transferred. Ifnum_bytes is greater than or equal to the size of the data associated with the trace event pointed to by theevent argument, all the recorded data shall be transferred. In this case, thetruncation-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 thenum_bytes argument is less than the length of recorded trace event data, the data transferred shall be truncated to a length ofnum_bytes, the value stored in the variable pointed to bydata_len shall be equal tonum_bytes, and thetruncation-status member of theevent structure argument shall be set to POSIX_TRACE_TRUNCATED_READ (see theposix_trace_event_infostructure defined in<trace.h>). 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.

RETURN VALUE top

Upon successful completion, these functions shall return a value of zero. Otherwise, they shall return the corresponding error number. If successful, these functions store: * The recorded trace event in the object pointed to byevent * The trace event information associated with the recorded trace event in the object pointed to bydata * The length of this trace event information in the object pointed to bydata_len * The value of zero in the object pointed to byunavailable

ERRORS top

These functions shall fail if:EINVALThe trace stream identifier argumenttrid is invalid. Theposix_trace_getnext_event() andposix_trace_timedgetnext_event() functions shall fail if:EINTRThe operation was interrupted by a signal, and so the call had no effect. Theposix_trace_trygetnext_event() function shall fail if:EINVALThe trace stream identifier argumenttrid does not correspond to an active trace stream. Theposix_trace_timedgetnext_event() function shall fail if:EINVALThere is no trace event immediately available from the trace stream, and thetimeout argument is invalid.ETIMEDOUT No trace event was available from the trace stream before the specified timeouttimeout expired.The following sections are informative.

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 athttp://www.opengroup.org/unix/online.html . 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, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group 2017POSIX_T...XT_EVENT(3P)