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