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