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