On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2009-01-10 09:41 @38.103.63.58 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
POSIX_TRACE_GETNEXT_EVENT(P) POSIX_TRACE_GETNEXT_EVENT(P)
NAME
posix_trace_getnext_event, posix_trace_timedgetnext_event, posix_trace_tryget-
next_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 abs_timeout);
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 identi-
fies 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 vari-
able 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_get-
next_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 abs_timeout expires, and the function shall return the error [ETIMEDOUT].
The timeout shall expire when the absolute time specified by abs_timeout passes, as
measured by the clock upon which timeouts are based (that is, when the value of
that clock equals or exceeds abs_timeout), or if the absolute time specified by
abs_timeout has already passed at the time of the call.
If the Timers option is supported, the timeout shall be based on the CLOCK_REAL-
TIME clock; if the Timers option is not supported, the timeout shall be based on
the system clock as returned by the time() function. 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 abs_timeout argu-
ment 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 argu-
ment 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 argu-
ment. 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_TRUN-
CATED_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_TRUN-
CATED_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 gener-
ated, 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 gen-
erated trace events.
RETURN VALUE
Upon successful completion, these functions shall return a value of zero. Other-
wise, 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
None.
SEE ALSO
posix_trace_create() , posix_trace_open() , the Base Definitions volume of
IEEE Std 1003.1-2001, <sys/types.h>, <trace.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating
System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C)
2001-2003 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 .
POSIX 2003 POSIX_TRACE_GETNEXT_EVENT(P)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2009-01-10 09:41 @38.103.63.58 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)