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