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 August 13, 2008 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.Nm bt_getprotobyname , 38.Nm bt_getprotobynumber , 39.Nm bt_getprotoent , 40.Nm bt_setprotoent , 41.Nm bt_endprotoent , 42.Nm bt_aton , 43.Nm bt_ntoa , 44.Nm bdaddr_same , 45.Nm bdaddr_any , 46.Nm bdaddr_copy 47.Nd Bluetooth routines 48.Sh LIBRARY 49.Lb libbluetooth 50.Sh SYNOPSIS 51.In bluetooth.h 52.Ft struct hostent * 53.Fn bt_gethostbyname "const char *name" 54.Ft struct hostent * 55.Fn bt_gethostbyaddr "const char *addr" "int len" "int type" 56.Ft struct hostent * 57.Fn bt_gethostent void 58.Ft void 59.Fn bt_sethostent "int stayopen" 60.Ft void 61.Fn bt_endhostent void 62.Ft struct protoent * 63.Fn bt_getprotobyname "const char *name" 64.Ft struct protoent * 65.Fn bt_getprotobynumber "int proto" 66.Ft struct protoent * 67.Fn bt_getprotoent void 68.Ft void 69.Fn bt_setprotoent "int stayopen" 70.Ft void 71.Fn bt_endprotoent void 72.Ft int 73.Fn bt_aton "const char *str" "bdaddr_t *ba" 74.Ft const char * 75.Fn bt_ntoa "const bdaddr_t *ba" "char *str" 76.Ft int 77.Fn bdaddr_same "const bdaddr_t *a" "const bdaddr_t *b" 78.Ft int 79.Fn bdaddr_any "const bdaddr_t *a" 80.Ft int 81.Fn bdaddr_copy "const bdaddr_t *dst" "const bdaddr_t *src" 82.Sh DESCRIPTION 83The 84.Fn bt_gethostent , 85.Fn bt_gethostbyname 86and 87.Fn bt_gethostbyaddr 88functions 89each return a pointer to an object with the 90.Vt hostent 91structure describing a Bluetooth host 92referenced by name or by address, respectively. 93.Pp 94The 95.Fa name 96argument passed to 97.Fn bt_gethostbyname 98should point to a 99.Dv NUL Ns -terminated 100hostname. 101The 102.Fa addr 103argument passed to 104.Fn bt_gethostbyaddr 105should point to an address which is 106.Fa len 107bytes long, 108in binary form 109(i.e., not a Bluetooth BD_ADDR in human readable 110.Tn ASCII 111form). 112The 113.Fa type 114argument specifies the address family of this address and must be set to 115.Dv AF_BLUETOOTH . 116.Pp 117The structure returned contains the information obtained from a line in 118.Pa /etc/bluetooth/hosts 119file. 120.Pp 121The 122.Fn bt_sethostent 123function controls whether 124.Pa /etc/bluetooth/hosts 125file should stay open after each call to 126.Fn bt_gethostbyname 127or 128.Fn bt_gethostbyaddr . 129If the 130.Fa stayopen 131flag is non-zero, the file will not be closed. 132.Pp 133The 134.Fn bt_endhostent 135function closes the 136.Pa /etc/bluetooth/hosts 137file. 138.Pp 139The 140.Fn bt_getprotoent , 141.Fn bt_getprotobyname 142and 143.Fn bt_getprotobynumber 144functions each return a pointer to an object with the 145.Vt protoent 146structure describing a Bluetooth Protocol Service Multiplexor referenced 147by name or number, respectively. 148.Pp 149The 150.Fa name 151argument passed to 152.Fn bt_getprotobyname 153should point to a 154.Dv NUL Ns -terminated 155Bluetooth Protocol Service Multiplexor name. 156The 157.Fa proto 158argument passed to 159.Fn bt_getprotobynumber 160should have numeric value of the desired Bluetooth Protocol Service Multiplexor. 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 internal static buffer will be used. 198.Pp 199The 200.Fn bdaddr_same , 201.Fn bdaddr_any 202and 203.Fn bdaddr_copy 204are handy shorthand Bluetooth address utility functions. 205The 206.Fn bdaddr_same 207function will test if two provided BD_ADDRs are the same. 208The 209.Fn bdaddr_any 210function will test if provided BD_ADDR is 211.Dv ANY 212BD_ADDR. 213The 214.Fn bdaddr_copy 215function will copy provided 216.Fa src 217BD_ADDR into provided 218.Fa dst 219BD_ADDR. 220.Sh FILES 221.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact 222.It Pa /etc/bluetooth/hosts 223.It Pa /etc/bluetooth/protocols 224.El 225.Sh EXAMPLES 226Print out the hostname associated with a specific BD_ADDR: 227.Bd -literal -offset indent 228const char *bdstr = "00:01:02:03:04:05"; 229bdaddr_t bd; 230struct hostent *hp; 231 232if (!bt_aton(bdstr, &bd)) 233 errx(1, "can't parse BD_ADDR %s", bdstr); 234 235if ((hp = bt_gethostbyaddr((const char *)&bd, 236 sizeof(bd), AF_BLUETOOTH)) == NULL) 237 errx(1, "no name associated with %s", bdstr); 238 239printf("name associated with %s is %s\en", bdstr, hp->h_name); 240.Ed 241.Sh DIAGNOSTICS 242Error return status from 243.Fn bt_gethostent , 244.Fn bt_gethostbyname 245and 246.Fn bt_gethostbyaddr 247is indicated by return of a 248.Dv NULL 249pointer. 250The external integer 251.Va h_errno 252may then be checked to see whether this is a temporary failure 253or an invalid or unknown host. 254The routine 255.Xr herror 3 256can be used to print an error message describing the failure. 257If its argument 258.Fa string 259is 260.Pf non- Dv NULL , 261it is printed, followed by a colon and a space. 262The error message is printed with a trailing newline. 263.Pp 264The variable 265.Va h_errno 266can have the following values: 267.Bl -tag -width ".Dv HOST_NOT_FOUND" 268.It Dv HOST_NOT_FOUND 269No such host is known. 270.It Dv NO_RECOVERY 271Some unexpected server failure was encountered. 272This is a non-recoverable error. 273.El 274.Pp 275The 276.Fn bt_getprotoent , 277.Fn bt_getprotobyname 278and 279.Fn bt_getprotobynumber 280return 281.Dv NULL 282on EOF or error. 283.Sh SEE ALSO 284.Xr gethostbyaddr 3 , 285.Xr gethostbyname 3 , 286.Xr getprotobyname 3 , 287.Xr getprotobynumber 3 , 288.Xr herror 3 , 289.Xr inet_aton 3 , 290.Xr inet_ntoa 3 291.Sh CAVEAT 292The 293.Fn bt_gethostent 294function reads the next line of 295.Pa /etc/bluetooth/hosts , 296opening the file if necessary. 297.Pp 298The 299.Fn bt_sethostent 300function opens and/or rewinds the 301.Pa /etc/bluetooth/hosts 302file. 303.Pp 304The 305.Fn bt_getprotoent 306function reads the next line of 307.Pa /etc/bluetooth/protocols , 308opening the file if necessary. 309.Pp 310The 311.Fn bt_setprotoent 312function opens and/or rewinds the 313.Pa /etc/bluetooth/protocols 314file. 315.Sh AUTHORS 316.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com 317.Sh BUGS 318These functions use static data storage; 319if the data is needed for future use, it should be 320copied before any subsequent calls overwrite it. 321