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