xref: /dragonfly/lib/libbluetooth/bluetooth.3 (revision 9f3fc534) 
1.\" $NetBSD: bluetooth.3,v 1.3 2006/07/30 00:15:54 wiz Exp $
2.\" $DragonFly: src/lib/libbluetooth/bluetooth.3,v 1.1 2008/01/03 11:47:52 hasso Exp $
3.\"
4.\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" $Id: bluetooth.3,v 1.3 2006/07/30 00:15:54 wiz Exp $
29.\" $FreeBSD: src/lib/libbluetooth/bluetooth.3,v 1.7 2005/01/21 10:26:11 ru Exp $
30.\"
31.Dd July 26, 2006
32.Dt BLUETOOTH 3
33.Os
34.Sh NAME
35.Nm bt_gethostbyname ,
36.Nm bt_gethostbyaddr ,
37.Nm bt_gethostent ,
38.Nm bt_sethostent ,
39.Nm bt_endhostent ,
40.Nm bt_getprotobyname ,
41.Nm bt_getprotobynumber ,
42.Nm bt_getprotoent ,
43.Nm bt_setprotoent ,
44.Nm bt_endprotoent ,
45.Nm bt_aton ,
46.Nm bt_ntoa ,
47.Nm bt_devaddr ,
48.Nm bt_devname ,
49.Nd Bluetooth routines
50.Sh LIBRARY
51.Lb libbluetooth
52.Sh SYNOPSIS
53.In bluetooth.h
54.Ft struct hostent *
55.Fn bt_gethostbyname "const char *name"
56.Ft struct hostent *
57.Fn bt_gethostbyaddr "const void *addr" "socklen_t len" "int type"
58.Ft struct hostent *
59.Fn bt_gethostent void
60.Ft void
61.Fn bt_sethostent "int stayopen"
62.Ft void
63.Fn bt_endhostent void
64.Ft struct protoent *
65.Fn bt_getprotobyname "const char *name"
66.Ft struct protoent *
67.Fn bt_getprotobynumber "int proto"
68.Ft struct protoent *
69.Fn bt_getprotoent void
70.Ft void
71.Fn bt_setprotoent "int stayopen"
72.Ft void
73.Fn bt_endprotoent void
74.Ft int
75.Fn bt_aton "const char *str" "bdaddr_t *ba"
76.Ft const char *
77.Fn bt_ntoa "const bdaddr_t *ba" "char *str"
78.Ft int
79.Fn bt_devaddr "const char *name" "bdaddr_t *addr"
80.Ft int
81.Fn bt_devname "char *name" "const bdaddr_t *addr"
82.Sh DESCRIPTION
83The
84.Fn bt_gethostent ,
85.Fn bt_gethostbyname ,
86and
87.Fn bt_gethostbyaddr
88functions each return a pointer to an object with the
89.Vt hostent
90structure describing a Bluetooth host
91referenced by name or by address, respectively.
92.Pp
93The
94.Fa name
95argument passed to
96.Fn bt_gethostbyname
97should point to a
98.Dv NUL Ns -terminated
99hostname.
100The
101.Fa addr
102argument passed to
103.Fn bt_gethostbyaddr
104should point to an address which is
105.Fa len
106bytes long,
107in binary form
108(i.e., not a Bluetooth BD_ADDR in human readable
109.Tn ASCII
110form).
111The
112.Fa type
113argument specifies the address family of this address and must be set to
114.Dv AF_BLUETOOTH .
115.Pp
116The structure returned contains the information obtained from a line in
117.Pa /etc/bluetooth/hosts
118file.
119.Pp
120The
121.Fn bt_sethostent
122function controls whether
123.Pa /etc/bluetooth/hosts
124file should stay open after each call to
125.Fn bt_gethostbyname
126or
127.Fn bt_gethostbyaddr .
128If the
129.Fa stayopen
130flag is non-zero, the file will not be closed.
131.Pp
132The
133.Fn bt_endhostent
134function closes the
135.Pa /etc/bluetooth/hosts
136file.
137.Pp
138The
139.Fn bt_getprotoent ,
140.Fn bt_getprotobyname ,
141and
142.Fn bt_getprotobynumber
143functions each return a pointer to an object with the
144.Vt protoent
145structure describing a Bluetooth Protocol Service Multiplexor referenced
146by name or number, respectively.
147.Pp
148The
149.Fa name
150argument passed to
151.Fn bt_getprotobyname
152should point to a
153.Dv NUL Ns -terminated
154Bluetooth Protocol Service Multiplexor name.
155The
156.Fa proto
157argument passed to
158.Fn bt_getprotobynumber
159should have numeric value of the desired Bluetooth Protocol Service
160Multiplexor.
161.Pp
162The structure returned contains the information obtained from a line in
163.Pa /etc/bluetooth/protocols
164file.
165.Pp
166The
167.Fn bt_setprotoent
168function controls whether
169.Pa /etc/bluetooth/protocols
170file should stay open after each call to
171.Fn bt_getprotobyname
172or
173.Fn bt_getprotobynumber .
174If the
175.Fa stayopen
176flag is non-zero, the file will not be closed.
177.Pp
178The
179.Fn bt_endprotoent
180function closes the
181.Pa /etc/bluetooth/protocols
182file.
183.Pp
184The
185.Fn bt_aton
186routine interprets the specified character string as a Bluetooth address,
187placing the address into the structure provided.
188It returns 1 if the string was successfully interpreted,
189or 0 if the string is invalid.
190.Pp
191The routine
192.Fn bt_ntoa
193takes a Bluetooth address and places an
194.Tn ASCII
195string representing the address into the buffer provided.
196It is up to the caller to ensure that provided buffer has enough space.
197If no buffer was provided then an internal static buffer will be used.
198.Pp
199The
200.Fn bt_devaddr
201function interprets the specified character string as the
202address or device name of a Bluetooth device on the local system, and
203places the device address in the structure provided, if any.
204It returns 1 if the string was successfully interpreted,
205or 0 if the string did not match any local device. The
206.Fn bt_devname
207function takes a Bluetooth device address and copies the local device
208name associated with that address into the buffer provided, if any.
209It returns 1 when the device was found, otherwise 0.
210.Sh FILES
211.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
212.It Pa /etc/bluetooth/hosts
213.It Pa /etc/bluetooth/protocols
214.El
215.Sh EXAMPLES
216Print out the hostname associated with a specific BD_ADDR:
217.Bd -literal -offset indent
218const char *bdstr = "00:01:02:03:04:05";
219bdaddr_t bd;
220struct hostent *hp;
221
222if (!bt_aton(bdstr, \*[Am]bd))
223	errx(1, "can't parse BD_ADDR %s", bdstr);
224
225if ((hp = bt_gethostbyaddr(\*[Am]bd, sizeof(bd),
226    AF_BLUETOOTH)) == NULL)
227	errx(1, "no name associated with %s", bdstr);
228
229printf("name associated with %s is %s\en", bdstr, hp-\*[Gt]h_name);
230.Ed
231.Sh DIAGNOSTICS
232Error return status from
233.Fn bt_gethostent ,
234.Fn bt_gethostbyname ,
235and
236.Fn bt_gethostbyaddr
237is indicated by return of a
238.Dv NULL
239pointer.
240The external integer
241.Va h_errno
242may then be checked to see whether this is a temporary failure
243or an invalid or unknown host.
244The routine
245.Xr herror 3
246can be used to print an error message describing the failure.
247If its argument
248.Fa string
249is
250.Pf non- Dv NULL ,
251it is printed, followed by a colon and a space.
252The error message is printed with a trailing newline.
253.Pp
254The variable
255.Va h_errno
256can have the following values:
257.Bl -tag -width ".Dv HOST_NOT_FOUND"
258.It Dv HOST_NOT_FOUND
259No such host is known.
260.It Dv NO_RECOVERY
261Some unexpected server failure was encountered.
262This is a non-recoverable error.
263.El
264.Pp
265The
266.Fn bt_getprotoent ,
267.Fn bt_getprotobyname ,
268and
269.Fn bt_getprotobynumber
270return
271.Dv NULL
272on EOF or error.
273.Sh SEE ALSO
274.Xr gethostbyaddr 3 ,
275.Xr gethostbyname 3 ,
276.Xr getprotobyname 3 ,
277.Xr getprotobynumber 3 ,
278.Xr herror 3 ,
279.Xr inet_aton 3 ,
280.Xr inet_ntoa 3
281.Sh HISTORY
282.Nm libbluetooth
283first appeared in
284.Fx
285was ported to
286.Nx 4.0
287and extended by
288.An Iain Hibbert
289for Itronix, Inc.
290.Nm libbluetooth
291was imported into
292.Dx 1.11 .
293.Sh AUTHORS
294.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
295.An Iain Hibbert
296.Sh CAVEATS
297The
298.Fn bt_gethostent
299function reads the next line of
300.Pa /etc/bluetooth/hosts ,
301opening the file if necessary.
302.Pp
303The
304.Fn bt_sethostent
305function opens and/or rewinds the
306.Pa /etc/bluetooth/hosts
307file.
308.Pp
309The
310.Fn bt_getprotoent
311function reads the next line of
312.Pa /etc/bluetooth/protocols ,
313opening the file if necessary.
314.Pp
315The
316.Fn bt_setprotoent
317function opens and/or rewinds the
318.Pa /etc/bluetooth/protocols
319file.
320.Sh BUGS
321These functions use static data storage;
322if the data is needed for future use, it should be
323copied before any subsequent calls overwrite it.
324