lib/libbluetooth/bluetooth.3

   1 .\" Copyright (c) 2003-2009 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 April 9, 2009
  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 bt_devaddr ,
  45 .Nm bt_devname ,
  46 .Nm bt_devinfo ,
  47 .Nm bt_devenum ,
  48 .Nm bt_devopen ,
  49 .Nm bt_devclose ,
  50 .Nm bt_devsend ,
  51 .Nm bt_devrecv ,
  52 .Nm bt_devreq ,
  53 .Nm bt_devfilter ,
  54 .Nm bt_devfilter_pkt_set ,
  55 .Nm bt_devfilter_pkt_clr ,
  56 .Nm bt_devfilter_pkt_tst ,
  57 .Nm bt_devfilter_evt_set ,
  58 .Nm bt_devfilter_evt_clr ,
  59 .Nm bt_devfilter_evt_tst ,
  60 .Nm bt_devinquiry ,
  61 .Nm bdaddr_same ,
  62 .Nm bdaddr_any ,
  63 .Nm bdaddr_copy
  64 .Nd Bluetooth routines
  65 .Sh LIBRARY
  66 .Lb libbluetooth
  67 .Sh SYNOPSIS
  68 .In bluetooth.h
  69 .Ft struct hostent *
  70 .Fn bt_gethostbyname "const char *name"
  71 .Ft struct hostent *
  72 .Fn bt_gethostbyaddr "const char *addr" "int len" "int type"
  73 .Ft struct hostent *
  74 .Fn bt_gethostent void
  75 .Ft void
  76 .Fn bt_sethostent "int stayopen"
  77 .Ft void
  78 .Fn bt_endhostent void
  79 .Ft struct protoent *
  80 .Fn bt_getprotobyname "const char *name"
  81 .Ft struct protoent *
  82 .Fn bt_getprotobynumber "int proto"
  83 .Ft struct protoent *
  84 .Fn bt_getprotoent void
  85 .Ft void
  86 .Fn bt_setprotoent "int stayopen"
  87 .Ft void
  88 .Fn bt_endprotoent void
  89 .Ft int
  90 .Fn bt_aton "const char *str" "bdaddr_t *ba"
  91 .Ft const char *
  92 .Fn bt_ntoa "const bdaddr_t *ba" "char *str"
  93 .Ft int
  94 .Fn bt_devaddr "const char *devname" "bdaddr_t *addr"
  95 .Ft int
  96 .Fn bt_devname "char *devname" "const bdaddr_t *addr"
  97 .Ft int
  98 .Fn (bt_devenum_cb_t) "int s" "struct bt_devinfo const *di" "void *arg"
  99 .Ft int
 100 .Fn bt_devinfo "struct bt_devinfo *di"
 101 .Ft int
 102 .Fn bt_devenum "bt_devenum_cb_t *cb" "void *arg"
 103 .Ft int
 104 .Fn bt_devopen "char const *devname"
 105 .Ft int
 106 .Fn bt_devclose "int s"
 107 .Ft int
 108 .Fn bt_devsend "int s" "uint16_t opcode" "void *param" "size_t plen"
 109 .Ft ssize_t
 110 .Fn bt_devrecv "int s" "void *buf" "size_t size" "time_t to"
 111 .Ft int
 112 .Fn bt_devreq "int s" "struct bt_devreq *r" "time_t to"
 113 .Ft int
 114 .Fn bt_devfilter "int s" "struct bt_devfilter const *new" "struct bt_devfilter *old"
 115 .Ft void
 116 .Fn bt_devfilter_pkt_set "struct bt_devfilter *filter" "uint8_t type"
 117 .Ft void
 118 .Fn bt_devfilter_pkt_clt "struct bt_devfilter *filter" "uint8_t type"
 119 .Ft int
 120 .Fn bt_devfilter_pkt_tst "struct bt_devfilter const *filter" "uint8_t type"
 121 .Ft void
 122 .Fn bt_devfilter_evt_set "struct bt_devfilter *filter" "uint8_t event"
 123 .Ft void
 124 .Fn bt_devfilter_evt_clt "struct bt_devfilter *filter" "uint8_t event"
 125 .Ft int
 126 .Fn bt_devfilter_evt_tst "struct bt_devfilter const *filter" "uint8_t event"
 127 .Ft int
 128 .Fn bt_devinquiry "char const *devname" "time_t length" "int num_rsp" "struct bt_devinquiry **ii"
 129 .Ft int
 130 .Fn bdaddr_same "const bdaddr_t *a" "const bdaddr_t *b"
 131 .Ft int
 132 .Fn bdaddr_any "const bdaddr_t *a"
 133 .Ft int
 134 .Fn bdaddr_copy "const bdaddr_t *dst" "const bdaddr_t *src"
 135 .Sh DESCRIPTION
 136 The
 137 .Fn bt_gethostent ,
 138 .Fn bt_gethostbyname
 139 and
 140 .Fn bt_gethostbyaddr
 141 functions
 142 each return a pointer to an object with the
 143 .Vt hostent
 144 structure describing a Bluetooth host
 145 referenced by name or by address, respectively.
 146 .Pp
 147 The
 148 .Fa name
 149 argument passed to
 150 .Fn bt_gethostbyname
 151 should point to a
 152 .Dv NUL Ns -terminated
 153 hostname.
 154 The
 155 .Fa addr
 156 argument passed to
 157 .Fn bt_gethostbyaddr
 158 should point to an address which is
 159 .Fa len
 160 bytes long,
 161 in binary form
 162 (i.e., not a Bluetooth BD_ADDR in human readable
 163 .Tn ASCII
 164 form).
 165 The
 166 .Fa type
 167 argument specifies the address family of this address and must be set to
 168 .Dv AF_BLUETOOTH .
 169 .Pp
 170 The structure returned contains the information obtained from a line in
 171 .Pa /etc/bluetooth/hosts
 172 file.
 173 .Pp
 174 The
 175 .Fn bt_sethostent
 176 function controls whether
 177 .Pa /etc/bluetooth/hosts
 178 file should stay open after each call to
 179 .Fn bt_gethostbyname
 180 or
 181 .Fn bt_gethostbyaddr .
 182 If the
 183 .Fa stayopen
 184 flag is non-zero, the file will not be closed.
 185 .Pp
 186 The
 187 .Fn bt_endhostent
 188 function closes the
 189 .Pa /etc/bluetooth/hosts
 190 file.
 191 .Pp
 192 The
 193 .Fn bt_getprotoent ,
 194 .Fn bt_getprotobyname
 195 and
 196 .Fn bt_getprotobynumber
 197 functions each return a pointer to an object with the
 198 .Vt protoent
 199 structure describing a Bluetooth Protocol Service Multiplexor referenced
 200 by name or number, respectively.
 201 .Pp
 202 The
 203 .Fa name
 204 argument passed to
 205 .Fn bt_getprotobyname
 206 should point to a
 207 .Dv NUL Ns -terminated
 208 Bluetooth Protocol Service Multiplexor name.
 209 The
 210 .Fa proto
 211 argument passed to
 212 .Fn bt_getprotobynumber
 213 should have numeric value of the desired Bluetooth Protocol Service Multiplexor.
 214 .Pp
 215 The structure returned contains the information obtained from a line in
 216 .Pa /etc/bluetooth/protocols
 217 file.
 218 .Pp
 219 The
 220 .Fn bt_setprotoent
 221 function controls whether
 222 .Pa /etc/bluetooth/protocols
 223 file should stay open after each call to
 224 .Fn bt_getprotobyname
 225 or
 226 .Fn bt_getprotobynumber .
 227 If the
 228 .Fa stayopen
 229 flag is non-zero, the file will not be closed.
 230 .Pp
 231 The
 232 .Fn bt_endprotoent
 233 function closes the
 234 .Pa /etc/bluetooth/protocols
 235 file.
 236 .Pp
 237 The
 238 .Fn bt_aton
 239 routine interprets the specified character string as a Bluetooth address,
 240 placing the address into the structure provided.
 241 It returns 1 if the string was successfully interpreted,
 242 or 0 if the string is invalid.
 243 .Pp
 244 The routine
 245 .Fn bt_ntoa
 246 takes a Bluetooth address and places an
 247 .Tn ASCII
 248 string representing the address into the buffer provided.
 249 It is up to the caller to ensure that provided buffer has enough space.
 250 If no buffer was provided then internal static buffer will be used.
 251 .Pp
 252 The
 253 .Fn bt_devaddr
 254 function interprets the specified
 255 .Fa devname
 256 string as the address or device name of a Bluetooth device on the local system,
 257 and places the device address in the provided
 258 .Fa bdaddr ,
 259 if any.
 260 The function returns 1 if the string was successfully interpreted,
 261 or 0 if the string did not match any local device.
 262 The
 263 .Fn bt_devname
 264 function takes a Bluetooth device address and copies the local device
 265 name associated with that address into the buffer provided,
 266 if any.
 267 Caller must ensure that provided buffer is at least
 268 .Dv HCI_DEVNAME_SIZE
 269 characters in size.
 270 The function returns 1 when the device was found,
 271 otherwise 0.
 272 .Pp
 273 The
 274 .Fn bt_devinfo
 275 function populates provided
 276 .Vt bt_devinfo
 277 structure with the information about given Bluetooth device.
 278 The caller is expected to pass Bluetooth device name in the
 279 .Fa devname
 280 field of the passed
 281 .Vt bt_devinfo
 282 structure.
 283 The function returns 0 when successful,
 284 otherwise -1.
 285 The
 286 .Vt bt_devinfo
 287 structure is defined as follows
 288 .Bd -literal -offset indent
 289 struct bt_devinfo
 290 {
 291         char            devname[HCI_DEVNAME_SIZE];
 292
 293         uint32_t        state;
 294
 295         bdaddr_t        bdaddr;
 296         uint16_t        _reserved0;
 297
 298         uint8_t         features[HCI_DEVFEATURES_SIZE];
 299
 300         /* buffer info */
 301         uint16_t        _reserved1;
 302         uint16_t        cmd_free;
 303         uint16_t        sco_size;
 304         uint16_t        sco_pkts;
 305         uint16_t        sco_free;
 306         uint16_t        acl_size;
 307         uint16_t        acl_pkts;
 308         uint16_t        acl_free;
 309
 310         /* stats */
 311         uint32_t        cmd_sent;
 312         uint32_t        evnt_recv;
 313         uint32_t        acl_recv;
 314         uint32_t        acl_sent;
 315         uint32_t        sco_recv;
 316         uint32_t        sco_sent;
 317         uint32_t        bytes_recv;
 318         uint32_t        bytes_sent;
 319
 320         /* misc/specific */
 321         uint16_t        link_policy_info;
 322         uint16_t        packet_type_info;
 323         uint16_t        role_switch_info;
 324         uint16_t        debug;
 325
 326         uint8_t         _padding[20];
 327 };
 328 .Ed
 329 .Pp
 330 The
 331 .Fn bt_devenum
 332 function enumerates Bluetooth devices present in the system.
 333 For every device found,
 334 the function will call provided
 335 .Fa cb
 336 callback function which should be of
 337 .Vt bt_devenum_cb_t
 338 type.
 339 The callback function is passed a
 340 .Dv HCI
 341 socket
 342 .Fa s ,
 343 fully populated
 344 .Vt bt_devinfo
 345 structure
 346 .Fa di
 347 and
 348 .Fa arg
 349 argument provided to the
 350 .Fn bt_devenum .
 351 The callback function can stop enumeration by returning a value
 352 that is greater than zero.
 353 The function returns number of successfully enumerated devices,
 354 or -1 if an error occurred.
 355 .Pp
 356 The
 357 .Fn bt_devopen
 358 function opens a Bluetooth device with the given
 359 .Fa devname
 360 and returns a connected and bound
 361 .Dv HCI
 362 socket handle.
 363 The function returns -1 if an error has occurred.
 364 .Pp
 365 The
 366 .Fn bt_devclose
 367 closes the passed
 368 .Dv HCI
 369 socket handle
 370 .Fa s ,
 371 previously obtained with
 372 .Xr bt_devopen 3 .
 373 .Pp
 374 The
 375 .Fn bt_devsend
 376 function sends a Bluetooth
 377 .Dv HCI
 378 command with the given
 379 .Fa opcode
 380 to the provided socket
 381 .Fa s ,
 382 previously obtained with
 383 .Xr bt_devopen 3 .
 384 The
 385 .Fa opcode
 386 parameter is expected to be in the host byte order.
 387 The
 388 .Fa param
 389 and
 390 .Fa plen
 391 parameters specify command parameters.
 392 The
 393 .Fn bt_devsend
 394 function does not modify the
 395 .Dv HCI
 396 filter on the provided socket
 397 .Fa s .
 398 The function returns 0 on success,
 399 or -1 if an error occurred.
 400 .Pp
 401 The
 402 .Fn bt_devrecv
 403 function receives one Bluetooth
 404 .Dv HCI
 405 packet from the socket
 406 .Fa s ,
 407 previously obtained with
 408 .Xr bt_devopen 3 .
 409 The packet is placed into the provided buffer
 410 .Fa buf
 411 of size
 412 .Fa size .
 413 The
 414 .Fa to
 415 parameter specifies receive timeout in seconds.
 416 Infinite timeout can be specified by passing negative value in the
 417 .Fa to
 418 parameter.
 419 The
 420 .Fn bt_devrecv
 421 function does not modify the
 422 .Dv HCI
 423 filter on the provided socket
 424 .Fa s .
 425 The function returns total number of bytes received,
 426 or -1 if an error occurred.
 427 .Pp
 428 The
 429 .Fn bt_devreq
 430 function makes a Bluetooth
 431 .Dv HCI
 432 request to the socket
 433 .Fa s ,
 434 previously obtained with
 435 .Xr bt_devopen 3 .
 436 The function will send the specified command and will wait for the specified
 437 event,
 438 or timeout
 439 .Fa to
 440 seconds to occur.
 441 The
 442 .Vt bt_devreq
 443 structure is defined as follows
 444 .Bd -literal -offset indent
 445 struct bt_devreq
 446 {
 447         uint16_t        opcode;
 448         uint8_t         event;
 449         void            *cparam;
 450         size_t          clen;
 451         void            *rparam;
 452         size_t          rlen;
 453 };
 454 .Ed
 455 .Pp
 456 The
 457 .Fa opcode
 458 field specifies the command and is expected to be in the host byte order.
 459 The
 460 .Fa cparam
 461 and
 462 .Fa clen
 463 fields specify command parameters data and command parameters data size
 464 respectively.
 465 The
 466 .Fa event
 467 field specifies which Bluetooth
 468 .Dv HCI
 469 event ID the function should wait for, otherwise it should be set to zero.
 470 The
 471 .Dv HCI
 472 Command Complete and Command Status events are enabled by default.
 473 The
 474 .Fa rparam
 475 and
 476 .Fa rlen
 477 parameters specify buffer and buffer size respectively where return
 478 parameters should be placed.
 479 The
 480 .Fn bt_devreq
 481 function temporarily modifies filter on the provided
 482 .Dv HCI
 483 socket
 484 .Fa s .
 485 The function returns 0 on success, or -1 if an error occurred.
 486 .Pp
 487 The
 488 .Fn bt_devfilter
 489 controls the local
 490 .Dv HCI
 491 filter associated with the socket
 492 .Fa s ,
 493 previously obtained with
 494 .Xr bt_devopen 3 .
 495 Filtering can be done on packet types, i.e.
 496 .Dv ACL ,
 497 .Dv SCO
 498 or
 499 .Dv HCI ,
 500 command and event packets, and, in addition, on
 501 .Dv HCI
 502 event IDs.
 503 Before applying the
 504 .Fa new
 505 filter (if provided) the function will try to obtain the current filter
 506 from the socket
 507 .Fa s
 508 and place it into the
 509 .Fa old
 510 parameter (if provided).
 511 The function returns 0 on success, or -1 if an error occurred.
 512 .Pp
 513 The
 514 .Fn bt_devfilter_pkt_set ,
 515 .Fn bt_devfilter_pkt_clr
 516 and
 517 .Fn bt_devfilter_pkt_tst
 518 functions can be used to modify and test the
 519 .Dv HCI
 520 filter
 521 .Fa filter .
 522 The
 523 .Fa type
 524 parameter specifies
 525 .Dv HCI
 526 packet type.
 527 .Pp
 528 The
 529 .Fn bt_devfilter_evt_set ,
 530 .Fn bt_devfilter_evt_clr
 531 and
 532 .Fn bt_devfilter_evt_tst
 533 functions can be used to modify and test the
 534 .Dv HCI
 535 event filter
 536 .Fa filter .
 537 The
 538 .Fa event
 539 parameter specifies
 540 .Dv HCI
 541 event ID.
 542 .Pp
 543 The
 544 .Fn bt_devinquiry
 545 function performs Bluetooth inquiry.
 546 The
 547 .Fa devname
 548 parameter specifies which local Bluetooth device should perform an inquiry.
 549 If not specified, i.e.
 550 .Dv NULL ,
 551 then first available device will be used.
 552 The
 553 .Fa length
 554 parameters specifies the total length of an inquiry in seconds.
 555 If not specified, i.e. 0, default value will be used.
 556 The
 557 .Fa num_rsp
 558 parameter specifies the number of responses that can be received before
 559 the inquiry is halted.
 560 If not specified, i.e. 0, default value will be used.
 561 The
 562 .Fa ii
 563 parameter specifies where to place inquiry results.
 564 On success, the function will return total number of inquiry results,
 565 will allocate,
 566 using
 567 .Xr calloc 3 ,
 568 buffer to store all the inquiry results and
 569 will return pointer to the allocated buffer in the
 570 .Fa ii
 571 parameter.
 572 It is up to the caller of the function to dispose of the buffer using
 573 .Xr free 3
 574 call.
 575 The function returns -1 if an error has occurred.
 576 The
 577 .Vt bt_devinquiry
 578 structure is defined as follows
 579 .Bd -literal -offset indent
 580 struct bt_devinquiry {
 581         bdaddr_t        bdaddr;
 582         uint8_t         pscan_rep_mode;
 583         uint8_t         pscan_period_mode;
 584         uint8_t         dev_class[3];
 585         uint16_t        clock_offset;
 586         int8_t          rssi;
 587         uint8_t         data[240];
 588 };
 589 .Ed
 590 .Pp
 591 The
 592 .Fn bdaddr_same ,
 593 .Fn bdaddr_any
 594 and
 595 .Fn bdaddr_copy
 596 are handy shorthand Bluetooth address utility functions.
 597 The
 598 .Fn bdaddr_same
 599 function will test if two provided BD_ADDRs are the same.
 600 The
 601 .Fn bdaddr_any
 602 function will test if provided BD_ADDR is
 603 .Dv ANY
 604 BD_ADDR.
 605 The
 606 .Fn bdaddr_copy
 607 function will copy provided
 608 .Fa src
 609 BD_ADDR into provided
 610 .Fa dst
 611 BD_ADDR.
 612 .Sh FILES
 613 .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
 614 .It Pa /etc/bluetooth/hosts
 615 .It Pa /etc/bluetooth/protocols
 616 .El
 617 .Sh EXAMPLES
 618 Print out the hostname associated with a specific BD_ADDR:
 619 .Bd -literal -offset indent
 620 const char *bdstr = "00:01:02:03:04:05";
 621 bdaddr_t bd;
 622 struct hostent *hp;
 623
 624 if (!bt_aton(bdstr, &bd))
 625         errx(1, "can't parse BD_ADDR %s", bdstr);
 626
 627 if ((hp = bt_gethostbyaddr((const char *)&bd,
 628     sizeof(bd), AF_BLUETOOTH)) == NULL)
 629         errx(1, "no name associated with %s", bdstr);
 630
 631 printf("name associated with %s is %s\en", bdstr, hp->h_name);
 632 .Ed
 633 .Sh DIAGNOSTICS
 634 Error return status from
 635 .Fn bt_gethostent ,
 636 .Fn bt_gethostbyname
 637 and
 638 .Fn bt_gethostbyaddr
 639 is indicated by return of a
 640 .Dv NULL
 641 pointer.
 642 The external integer
 643 .Va h_errno
 644 may then be checked to see whether this is a temporary failure
 645 or an invalid or unknown host.
 646 The routine
 647 .Xr herror 3
 648 can be used to print an error message describing the failure.
 649 If its argument
 650 .Fa string
 651 is
 652 .Pf non- Dv NULL ,
 653 it is printed, followed by a colon and a space.
 654 The error message is printed with a trailing newline.
 655 .Pp
 656 The variable
 657 .Va h_errno
 658 can have the following values:
 659 .Bl -tag -width ".Dv HOST_NOT_FOUND"
 660 .It Dv HOST_NOT_FOUND
 661 No such host is known.
 662 .It Dv NO_RECOVERY
 663 Some unexpected server failure was encountered.
 664 This is a non-recoverable error.
 665 .El
 666 .Pp
 667 The
 668 .Fn bt_getprotoent ,
 669 .Fn bt_getprotobyname
 670 and
 671 .Fn bt_getprotobynumber
 672 return
 673 .Dv NULL
 674 on EOF or error.
 675 .Sh SEE ALSO
 676 .Xr gethostbyaddr 3 ,
 677 .Xr gethostbyname 3 ,
 678 .Xr getprotobyname 3 ,
 679 .Xr getprotobynumber 3 ,
 680 .Xr herror 3 ,
 681 .Xr inet_aton 3 ,
 682 .Xr inet_ntoa 3 ,
 683 .Xr ng_hci 4
 684 .Sh CAVEAT
 685 The
 686 .Fn bt_gethostent
 687 function reads the next line of
 688 .Pa /etc/bluetooth/hosts ,
 689 opening the file if necessary.
 690 .Pp
 691 The
 692 .Fn bt_sethostent
 693 function opens and/or rewinds the
 694 .Pa /etc/bluetooth/hosts
 695 file.
 696 .Pp
 697 The
 698 .Fn bt_getprotoent
 699 function reads the next line of
 700 .Pa /etc/bluetooth/protocols ,
 701 opening the file if necessary.
 702 .Pp
 703 The
 704 .Fn bt_setprotoent
 705 function opens and/or rewinds the
 706 .Pa /etc/bluetooth/protocols
 707 file.
 708 .Pp
 709 The
 710 .Fn bt_devenum
 711 function enumerates up to
 712 .Dv HCI_DEVMAX
 713 Bluetooth devices.
 714 During enumeration the
 715 .Fn bt_devenum
 716 function uses the same
 717 .Dv HCI
 718 socket.
 719 The function guarantees that the socket,
 720 passed to the callback function,
 721 will be bound and connected to the Bluetooth device being enumerated.
 722 .Sh AUTHORS
 723 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 724 .Sh BUGS
 725 Some of those functions use static data storage;
 726 if the data is needed for future use, it should be
 727 copied before any subsequent calls overwrite it.