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 $
4 .\" Copyright (c) 2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
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 $
35 .Nm bt_gethostbyname ,
36 .Nm bt_gethostbyaddr ,
40 .Nm bt_getprotobyname ,
41 .Nm bt_getprotobynumber ,
49 .Nd Bluetooth routines
55 .Fn bt_gethostbyname "const char *name"
57 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
59 .Fn bt_gethostent void
61 .Fn bt_sethostent "int stayopen"
63 .Fn bt_endhostent void
65 .Fn bt_getprotobyname "const char *name"
67 .Fn bt_getprotobynumber "int proto"
69 .Fn bt_getprotoent void
71 .Fn bt_setprotoent "int stayopen"
73 .Fn bt_endprotoent void
75 .Fn bt_aton "const char *str" "bdaddr_t *ba"
77 .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
79 .Fn bt_devaddr "const char *name" "bdaddr_t *addr"
81 .Fn bt_devname "char *name" "const bdaddr_t *addr"
85 .Fn bt_gethostbyname ,
88 functions each return a pointer to an object with the
90 structure describing a Bluetooth host
91 referenced by name or by address, respectively.
98 .Dv NUL Ns -terminated
104 should point to an address which is
108 (i.e., not a Bluetooth BD_ADDR in human readable
113 argument specifies the address family of this address and must be set to
116 The structure returned contains the information obtained from a line in
117 .Pa /etc/bluetooth/hosts
122 function controls whether
123 .Pa /etc/bluetooth/hosts
124 file should stay open after each call to
127 .Fn bt_gethostbyaddr .
130 flag is non-zero, the file will not be closed.
135 .Pa /etc/bluetooth/hosts
140 .Fn bt_getprotobyname ,
142 .Fn bt_getprotobynumber
143 functions each return a pointer to an object with the
145 structure describing a Bluetooth Protocol Service Multiplexor referenced
146 by name or number, respectively.
151 .Fn bt_getprotobyname
153 .Dv NUL Ns -terminated
154 Bluetooth Protocol Service Multiplexor name.
158 .Fn bt_getprotobynumber
159 should have numeric value of the desired Bluetooth Protocol Service
162 The structure returned contains the information obtained from a line in
163 .Pa /etc/bluetooth/protocols
168 function controls whether
169 .Pa /etc/bluetooth/protocols
170 file should stay open after each call to
171 .Fn bt_getprotobyname
173 .Fn bt_getprotobynumber .
176 flag is non-zero, the file will not be closed.
181 .Pa /etc/bluetooth/protocols
186 routine interprets the specified character string as a Bluetooth address,
187 placing the address into the structure provided.
188 It returns 1 if the string was successfully interpreted,
189 or 0 if the string is invalid.
193 takes a Bluetooth address and places an
195 string representing the address into the buffer provided.
196 It is up to the caller to ensure that provided buffer has enough space.
197 If no buffer was provided then an internal static buffer will be used.
201 function interprets the specified character string as the
202 address or device name of a Bluetooth device on the local system, and
203 places the device address in the structure provided, if any.
204 It returns 1 if the string was successfully interpreted,
205 or 0 if the string did not match any local device. The
207 function takes a Bluetooth device address and copies the local device
208 name associated with that address into the buffer provided, if any.
209 It returns 1 when the device was found, otherwise 0.
211 .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
212 .It Pa /etc/bluetooth/hosts
213 .It Pa /etc/bluetooth/protocols
216 Print out the hostname associated with a specific BD_ADDR:
217 .Bd -literal -offset indent
218 const char *bdstr = "00:01:02:03:04:05";
222 if (!bt_aton(bdstr, \*[Am]bd))
223 errx(1, "can't parse BD_ADDR %s", bdstr);
225 if ((hp = bt_gethostbyaddr((const char *)\*[Am]bd,
226 sizeof(bd), AF_BLUETOOTH)) == NULL)
227 errx(1, "no name associated with %s", bdstr);
229 printf("name associated with %s is %s\en", bdstr, hp-\*[Gt]h_name);
232 Error return status from
234 .Fn bt_gethostbyname ,
237 is indicated by return of a
242 may then be checked to see whether this is a temporary failure
243 or an invalid or unknown host.
246 can be used to print an error message describing the failure.
251 it is printed, followed by a colon and a space.
252 The error message is printed with a trailing newline.
256 can have the following values:
257 .Bl -tag -width ".Dv HOST_NOT_FOUND"
258 .It Dv HOST_NOT_FOUND
259 No such host is known.
261 Some unexpected server failure was encountered.
262 This is a non-recoverable error.
267 .Fn bt_getprotobyname ,
269 .Fn bt_getprotobynumber
274 .Xr gethostbyaddr 3 ,
275 .Xr gethostbyname 3 ,
276 .Xr getprotobyname 3 ,
277 .Xr getprotobynumber 3 ,
294 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
299 function reads the next line of
300 .Pa /etc/bluetooth/hosts ,
301 opening the file if necessary.
305 function opens and/or rewinds the
306 .Pa /etc/bluetooth/hosts
311 function reads the next line of
312 .Pa /etc/bluetooth/protocols ,
313 opening the file if necessary.
317 function opens and/or rewinds the
318 .Pa /etc/bluetooth/protocols
321 These functions use static data storage;
322 if the data is needed for future use, it should be
323 copied before any subsequent calls overwrite it.