bb_list(3EXT)

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

NAME

bb_list- Get information about black boxes

SYNOPSIS

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

int bb_list(bb_status_t *status, uint_t *nstatus);

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

status(OUT):

An array of bb_status_ts.

nstatus (IN/OUT):

Points to the number of bb_status_ts passed in status

DESCRIPTION

bb_list() gives information about the set of black boxes on the node, by filling in the members of the status array. For each bb_status_t returned:

• The bbs_state member is one of the values of the bb_state_t enumeration.

• If bbs_state is BBS_FROZEN, bbs_freezetime is the time that the black box was frozen. If bbs_state is some other value, the value of bbs_freezetime is undefined.

• The bbs_size member is the size in bytes used to make up each buffer in the black box. Since each black box may have more than one buffer, the black box may use more total space than is indicated by bbs_size, but it is only guaranteed to have as much space as is indicated here. This can be used to determine how many events the black box is guaranteed to be able to store.

• The bbs_count member is the number of events currently stored in all buffers of the black box being described. The bb_event_t returned by bb_read uses statically-sized buffers, so the black box is only guaranteed to be able to store (bbs_size / sizeof (bb_event_t)) events at once. However, the events may be represented differently within the black box, which may allow more events to be stored, particularly if the events don't use all BB_MSG_MAX bytes of the event message body. This parameter can be used to get an approximation of how much space is necessary to capture some number of events from a given workload.

• The bbs_ndropped member is the number of events dropped while events were being logged to this black box, i.e. were overwritten. It is reset when a black box is released through bb_release(). On nodes not using a fully persistent black box, this can be used to help tune the rate of the flushing daemon.

• The bbs_name member is the pathname of the persistent store holding the black box being described.

The caller can call bb_getnbb() first, to determine the number of black boxes configured on the node. When calling bb_list(), nstatus should point to the number of bb_status_ts passed in status. On successful return, nstatus will be filled in with the number of configured black boxes on the node.

If nstatus is less than the number of configured black boxes, status will be filled in with information about the first nstatus black boxes on the node.

RETURN VALUES

bb_list() returns 0 on success and -1 on failure.

ERRORS

If it returns -1, the value of status and nstatus are undefined, and errno is set to:

EFAULT

The status or nstatus argument points to an illegal address

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

bb_release(3EXT)

bb_getnbb(3EXT)

ChorusOS 5.0  Last Revised December 2001

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