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