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