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