lib/libbluetooth/bluetooth.3

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