1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
.TH NJB_DISCOVER 3 "March 2001"
.SH NAME
NJB_Discover \- Locate NJB devices on available USB busses
.SH LIBRARY
libnjb
.SH SYNOPSIS
#include <libnjb.h>
extern int njb_error;
int NJB_Discover (njb_t
.BR *njbs ,
int
.BR limit ,
int
.BR *n )
.SH DESCRIPTION
This function searches all configured USB busses for attached NJB
devices.
The number of NJB devices found is placed into
.BR n ,
and the njb_t array
.B *njbs
is populated with
.B n
elements, describing the NJB's in the order in which they are found.
It is the user's responsibility to ensure that the
.B *njbs
array is of sufficient size. A good practice is to declare an array
with NJB_MAX_DEVICES elements: while this is slightly wasteful in
terms of memory, it will always guarantee that sufficient storage
is available.
The
.B limit
parameter can be used to restrict the search to
.B limit
busses (starting with /dev/usb0, and counting up). If set to 0, then
no limit is enforced, and all busses will be queried.
.SH RETURN VALUES
NJB_Discover returns 0 if no errors occurred. If any
errors were encountered during the search, then -1 is returned.
.B njb_error
will not be set to a meaningful value, but the
.BR 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
.B 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 entirely 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
.B n
would be set to 1, and the
.B njbs
array would have a valid NJB device in described in
.BR njbs[0] "."
Conversely, NJB_Discover can return 0 even if no NJB devices 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.
.SH SEE ALSO
njb_error(3)
.SH BUGS
The author is aware that the term "USB busses" is redundant (like
"ATM machine"). It would be more correct to say "USBs", but that
doesn't flow as well.
|