lib/libbluetooth/bluetooth.3

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