njb_discover(3)

NAME

NJB_Discover - Locate NJB devices on available USB busses

LIBRARY

libnjb

SYNOPSIS

#include <libnjb.h>
extern int njb_error;
int NJB_Discover (njb_t *njbs, int limit, int *n)

DESCRIPTION

This function searches all configured USB busses for at

tached NJB devices.

The number of NJB devices found is placed into n, and the

njb_t array *njbs is populated with n elements, describing the

NJB's in the order in which they are found. It is the user's re

sponsibility to ensure that the *njbs array is of sufficient

size. A good practice is to declare an array with NJB_MAX_DE

VICES elements: while this is slightly wasteful in terms of memo

ry, it will always guarantee that sufficient storage is avail

able.

The limit parameter can be used to restrict the search to

limit busses (starting with /dev/usb0, and counting up). If set

to 0, then no limit is enforced, and all busses will be queried.

RETURN VALUES

NJB_Discover returns 0 if no errors occurred. If any er

rors were encountered during the search, then -1 is returned.

njb_error will not be set to a meaningful value, but the

njb_error(3) functions can still be used to obtain error messages

corresponding to the problems found.

It is extremely important to note that an error does not

automatically imply a failure. You should always check the value

stored in n to determine how many NJB devices were discovered, if

any, regardless of the return value of NJB_Discover. Because

multiple USB controllers can be present on a system, it is en

tirely possible, for example, that /dev/usb1 could not be opened

while an NJB device on /dev/usb0 was located successfully. In

this case, NJB_Discover would still return -1, but n would be set

to 1, and the njbs array would have a valid NJB device in de

scribed in njbs[0].

Conversely, NJB_Discover can return 0 even if no NJB de

vices are found. In this case, there were no errors opening the

available USB busses, but no NJB devices were attached and/or

ready for communication.

SEE ALSO

njb_error(3)

BUGS

The author is aware that the term "USB busses" is redun

dant (like "ATM machine"). It would be more correct to say "US

Bs", but that doesn't flow as well.

March 2001

NJB_DISCOVER(3)