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