diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/posix_trace_getnext_event.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/posix_trace_getnext_event.3p | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/posix_trace_getnext_event.3p b/man-pages-posix-2013/man3p/posix_trace_getnext_event.3p new file mode 100644 index 0000000..581ed23 --- /dev/null +++ b/man-pages-posix-2013/man3p/posix_trace_getnext_event.3p @@ -0,0 +1,265 @@ +'\" et +.TH POSIX_TRACE_GETNEXT_EVENT "3P" 2013 "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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |