# posix_trace_getnext_event

## 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.
    


## NAME



           posix_trace_getnext_event, posix_trace_timedgetnext_event,
           posix_trace_trygetnext_event — retrieve a trace event (**TRACING**)
    


## SYNOPSIS



           #include <sys/types.h>
           #include <trace.h>
    
           int posix_trace_getnext_event(trace_id_t _trid_ ,
               struct posix_trace_event_info *restrict _event_ ,
               void *restrict _data_ , size_t _num_bytes_ ,
               size_t *restrict _data_len_ , int *restrict _unavailable_);
           int posix_trace_timedgetnext_event(trace_id_t _trid_ ,
               struct posix_trace_event_info *restrict _event_ ,
               void *restrict _data_ , size_t _num_bytes_ ,
               size_t *restrict _data_len_ , int *restrict _unavailable_ ,
               const struct timespec *restrict _abstime_);
           int posix_trace_trygetnext_event(trace_id_t _trid_ ,
               struct posix_trace_event_info *restrict _event_ ,
               void *restrict _data_ , size_t _num_bytes_ ,
               size_t *restrict _data_len_ , int *restrict _unavailable_);
    


## DESCRIPTION



           The _posix_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 the _trid_ argument.  The
           _posix_trace_trygetnext_event_() function shall report a recorded
           trace event from an active trace stream without log identified by
           the _trid_ argument.
    
           The trace event information associated with the recorded trace
           event shall be copied by the function into the structure pointed
           to by the argument _event_ and the data associated with the trace
           event shall be copied into the buffer pointed to by the _data_
           argument.
    
           The _posix_trace_getnext_event_() function shall block if the _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
           _unavailable_ argument shall be set to zero. Otherwise, the variable
           pointed to by the _unavailable_ argument shall be set to a value
           different from zero.
    
           The _posix_trace_timedgetnext_event_() function shall attempt to get
           another trace event from an active trace stream without log, as in
           the _posix_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 argument _abstime_
           expires, and the function shall return the error **[ETIMEDOUT]**.
    
           The timeout shall expire when the absolute time specified by
           _abstime_ passes, as measured by the clock upon which timeouts are
           based (that is, when the value of that clock equals or exceeds
           _abstime_), or if the absolute time specified by _abstime_ 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. The **timespec** data 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 the _abstime_ 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.
    
           The _posix_trace_trygetnext_event_() function shall not block.  This
           function shall return an error if the _trid_ argument identifies a
           pre-recorded trace stream.  If a recorded trace event was
           reported, the variable pointed to by the _unavailable_ argument
           shall be set to zero. Otherwise, if no trace event was reported,
           the variable pointed to by the _unavailable_ argument shall be set
           to a value different from zero.
    
           The argument _num_bytes_ shall be the size of the buffer pointed to
           by the _data_ argument. The argument _data_len_ reports to the
           application the length in bytes of the data record just
           transferred. If _num_bytes_ is greater than or equal to the size of
           the data associated with the trace event pointed to by the _event_
           argument, all the recorded data shall be transferred. In this
           case, the _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 _num_bytes_ argument is less
           than the length of recorded trace event data, the data transferred
           shall be truncated to a length of _num_bytes_ , the value stored in
           the variable pointed to by _data_len_ shall be equal to _num_bytes_ ,
           and the _truncation-status_ member of the _event_ structure argument
           shall be set to POSIX_TRACE_TRUNCATED_READ (see the
           **posix_trace_event_info** structure 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



           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 by _event_
    
            *  The trace event information associated with the recorded trace
               event in the object pointed to by _data_
    
            *  The length of this trace event information in the object
               pointed to by _data_len_
    
            *  The value of zero in the object pointed to by _unavailable_
    


## ERRORS



           These functions shall fail if:
    
           **EINVAL** The trace stream identifier argument _trid_ is invalid.
    
           The _posix_trace_getnext_event_() and
           _posix_trace_timedgetnext_event_() functions shall fail if:
    
           **EINTR** The operation was interrupted by a signal, and so the call
                  had no effect.
    
           The _posix_trace_trygetnext_event_() function shall fail if:
    
           **EINVAL** The trace stream identifier argument _trid_ does not
                  correspond to an active trace stream.
    
           The _posix_trace_timedgetnext_event_() function shall fail if:
    
           **EINVAL** There is no trace event immediately available from the
                  trace stream, and the _timeout_ argument is invalid.
    
           **ETIMEDOUT**
                  No trace event was available from the trace stream before
                  the specified timeout _timeout_ expired.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           These functions may be removed in a future version.
    


* * *