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