bb_read(3EXT)

NAME | SYNOPSIS | API RESTRICTIONS | ARGUMENTS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

NAME

bb_read- read a frozen black box

SYNOPSIS

$(OS_DIR)/lib/libblackbox.a
#include <sys/blackbox.h>

int bb_read(bb_handle_t hdl, bb_event_t *events, ulong_t nevent);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

ARGUMENTS

hdl(IN):

A handle returned by bb_open(), which serves as an opaque pointer into the black box

events(OUT):

An array of nevent bb_event_ts

nevent(IN):

The number of bb_event_ts passed in events

DESCRIPTION

bb_read() reads events from a frozen black box.

Upon successful return from bb_read(), events will be filled in with valid bb_event_ts from the black box.

By calling bb_read() repeatedly until it returns 0, the entire contents of a given black box can be read; each event will have been returned exactly once. The order of the returned events is not defined, but event order can be reconstructed by sorting the entire array of events by timestamp.

There is no way to search within a black box, and opening multiple handles to a black box is impossible. Once a bb_read() returns 0, the handle is no longer valid.

RETURN VALUES

bb_read() returns the number of events read on success, and -1 on failure.

ERRORS

If it returns -1, events and nevents remain unmodified, and errno is set to:

EBADF:

hdl is not a valid handle

EFAULT:

The events or nevents argument points to an illegal address

EINVAL:

The black box is not open

If EBADF is returned, events and nevents remain unmodified; if EFAULT is returned, the contents of events and nevents are undefined.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

bb_open(3EXT)

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | ARGUMENTS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO