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 or 498.Dv HCI , 499command and event packets, and, in addition, on 500.Dv HCI 501event IDs. 502Before applying the 503.Fa new 504filter (if provided) the function will try to obtain the current filter 505from the socket 506.Fa s 507and place it into the 508.Fa old 509parameter (if provided). 510The function returns 0 on success, or -1 if an error occurred. 511.Pp 512The 513.Fn bt_devfilter_pkt_set , 514.Fn bt_devfilter_pkt_clr 515and 516.Fn bt_devfilter_pkt_tst 517functions can be used to modify and test the 518.Dv HCI 519filter 520.Fa filter . 521The 522.Fa type 523parameter specifies 524.Dv HCI 525packet type. 526.Pp 527The 528.Fn bt_devfilter_evt_set , 529.Fn bt_devfilter_evt_clr 530and 531.Fn bt_devfilter_evt_tst 532functions can be used to modify and test the 533.Dv HCI 534event filter 535.Fa filter . 536The 537.Fa event 538parameter specifies 539.Dv HCI 540event ID. 541.Pp 542The 543.Fn bt_devinquiry 544function performs Bluetooth inquiry. 545The 546.Fa devname 547parameter specifies which local Bluetooth device should perform an inquiry. 548If not specified, i.e. 549.Dv NULL , 550then first available device will be used. 551The 552.Fa length 553parameters specifies the total length of an inquiry in seconds. 554If not specified, i.e. 0, default value will be used. 555The 556.Fa num_rsp 557parameter specifies the number of responses that can be received before 558the inquiry is halted. 559If not specified, i.e. 0, default value will be used. 560The 561.Fa ii 562parameter specifies where to place inquiry results. 563On success, the function will return total number of inquiry results, 564will allocate, 565using 566.Xr calloc 3 , 567buffer to store all the inquiry results and 568will return pointer to the allocated buffer in the 569.Fa ii 570parameter. 571It is up to the caller of the function to dispose of the buffer using 572.Xr free 3 573call. 574The function returns -1 if an error has occurred. 575The 576.Vt bt_devinquiry 577structure is defined as follows 578.Bd -literal -offset indent 579struct bt_devinquiry { 580 bdaddr_t bdaddr; 581 uint8_t pscan_rep_mode; 582 uint8_t pscan_period_mode; 583 uint8_t dev_class[3]; 584 uint16_t clock_offset; 585 int8_t rssi; 586 uint8_t data[240]; 587}; 588.Ed 589.Pp 590The 591.Fn bdaddr_same , 592.Fn bdaddr_any 593and 594.Fn bdaddr_copy 595are handy shorthand Bluetooth address utility functions. 596The 597.Fn bdaddr_same 598function will test if two provided BD_ADDRs are the same. 599The 600.Fn bdaddr_any 601function will test if provided BD_ADDR is 602.Dv ANY 603BD_ADDR. 604The 605.Fn bdaddr_copy 606function will copy provided 607.Fa src 608BD_ADDR into provided 609.Fa dst 610BD_ADDR. 611.Sh FILES 612.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact 613.It Pa /etc/bluetooth/hosts 614.It Pa /etc/bluetooth/protocols 615.El 616.Sh EXAMPLES 617Print out the hostname associated with a specific BD_ADDR: 618.Bd -literal -offset indent 619const char *bdstr = "00:01:02:03:04:05"; 620bdaddr_t bd; 621struct hostent *hp; 622 623if (!bt_aton(bdstr, &bd)) 624 errx(1, "can't parse BD_ADDR %s", bdstr); 625 626if ((hp = bt_gethostbyaddr((const char *)&bd, 627 sizeof(bd), AF_BLUETOOTH)) == NULL) 628 errx(1, "no name associated with %s", bdstr); 629 630printf("name associated with %s is %s\en", bdstr, hp->h_name); 631.Ed 632.Sh DIAGNOSTICS 633Error return status from 634.Fn bt_gethostent , 635.Fn bt_gethostbyname 636and 637.Fn bt_gethostbyaddr 638is indicated by return of a 639.Dv NULL 640pointer. 641The external integer 642.Va h_errno 643may then be checked to see whether this is a temporary failure 644or an invalid or unknown host. 645The routine 646.Xr herror 3 647can be used to print an error message describing the failure. 648If its argument 649.Fa string 650is 651.Pf non- Dv NULL , 652it is printed, followed by a colon and a space. 653The error message is printed with a trailing newline. 654.Pp 655The variable 656.Va h_errno 657can have the following values: 658.Bl -tag -width ".Dv HOST_NOT_FOUND" 659.It Dv HOST_NOT_FOUND 660No such host is known. 661.It Dv NO_RECOVERY 662Some unexpected server failure was encountered. 663This is a non-recoverable error. 664.El 665.Pp 666The 667.Fn bt_getprotoent , 668.Fn bt_getprotobyname 669and 670.Fn bt_getprotobynumber 671return 672.Dv NULL 673on EOF or error. 674.Sh SEE ALSO 675.Xr gethostbyaddr 3 , 676.Xr gethostbyname 3 , 677.Xr getprotobyname 3 , 678.Xr getprotobynumber 3 , 679.Xr herror 3 , 680.Xr inet_aton 3 , 681.Xr inet_ntoa 3 , 682.Xr ng_hci 4 683.Sh CAVEAT 684The 685.Fn bt_gethostent 686function reads the next line of 687.Pa /etc/bluetooth/hosts , 688opening the file if necessary. 689.Pp 690The 691.Fn bt_sethostent 692function opens and/or rewinds the 693.Pa /etc/bluetooth/hosts 694file. 695.Pp 696The 697.Fn bt_getprotoent 698function reads the next line of 699.Pa /etc/bluetooth/protocols , 700opening the file if necessary. 701.Pp 702The 703.Fn bt_setprotoent 704function opens and/or rewinds the 705.Pa /etc/bluetooth/protocols 706file. 707.Pp 708The 709.Fn bt_devenum 710function enumerates up to 711.Dv HCI_DEVMAX 712Bluetooth devices. 713During enumeration the 714.Fn bt_devenum 715function uses the same 716.Dv HCI 717socket. 718The function guarantees that the socket, 719passed to the callback function, 720will be bound and connected to the Bluetooth device being enumerated. 721.Sh AUTHORS 722.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com 723.Sh BUGS 724Some of those functions use static data storage; 725if the data is needed for future use, it should be 726copied before any subsequent calls overwrite it. 727