---
name: "bluetooth"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/bdaddr_any"
---

# bluetooth(3)

Bluetooth routines

Part of [bdaddr\_any(3)](/bdaddr_any/3.md).

## NAME

**bt\_gethostbyname**, **bt\_gethostbyaddr**, **bt\_gethostent**, **bt\_sethostent**, **bt\_endhostent**, **bt\_getprotobyname**, **bt\_getprotobynumber**, **bt\_getprotoent**, **bt\_setprotoent**, **bt\_endprotoent**, **bt\_aton**, **bt\_ntoa**, **bt\_devaddr**, **bt\_devname**, **bt\_devinfo**, **bt\_devenum**, **bt\_devopen**, **bt\_devclose**, **bt\_devsend**, **bt\_devrecv**, **bt\_devreq**, **bt\_devfilter**, **bt\_devfilter\_pkt\_set**, **bt\_devfilter\_pkt\_clr**, **bt\_devfilter\_pkt\_tst**, **bt\_devfilter\_evt\_set**, **bt\_devfilter\_evt\_clr**, **bt\_devfilter\_evt\_tst**, **bt\_devinquiry**, **bt\_devremote\_name**, **bt\_devremote\_name\_gen**, **bdaddr\_same**, **bdaddr\_any**, **bdaddr\_copy** – Bluetooth routines

## LIBRARY

library “libbluetooth”

## SYNOPSIS

**#include \<bluetooth.h\>**

*struct* *hostent* *\**\

**bt\_gethostbyname**(*const char \*name*);

*struct* *hostent* *\**\

**bt\_gethostbyaddr**(*const char \*addr*, *int len*, *int type*);

*struct* *hostent* *\**\

**bt\_gethostent**(*void*);

*void*\

**bt\_sethostent**(*int stayopen*);

*void*\

**bt\_endhostent**(*void*);

*struct* *protoent* *\**\

**bt\_getprotobyname**(*const char \*name*);

*struct* *protoent* *\**\

**bt\_getprotobynumber**(*int proto*);

*struct* *protoent* *\**\

**bt\_getprotoent**(*void*);

*void*\

**bt\_setprotoent**(*int stayopen*);

*void*\

**bt\_endprotoent**(*void*);

*int*\

**bt\_aton**(*const char \*str*, *bdaddr\_t \*ba*);

*const* *char* *\**\

**bt\_ntoa**(*const bdaddr\_t \*ba*, *char \*str*);

*int*\

**bt\_devaddr**(*const char \*devname*, *bdaddr\_t \*addr*);

*int*\

**bt\_devname**(*char \*devname*, *const bdaddr\_t \*addr*);

*int*\

**(bt\_devenum\_cb\_t)**(*int s*, *struct bt\_devinfo const \*di*, *void \*arg*);

*int*\

**bt\_devinfo**(*struct bt\_devinfo \*di*);

*int*\

**bt\_devenum**(*bt\_devenum\_cb\_t \*cb*, *void \*arg*);

*int*\

**bt\_devopen**(*char const \*devname*);

*int*\

**bt\_devclose**(*int s*);

*int*\

**bt\_devsend**(*int s*, *uint16\_t opcode*, *void \*param*, *size\_t plen*);

*ssize\_t*\

**bt\_devrecv**(*int s*, *void \*buf*, *size\_t size*, *time\_t to*);

*int*\

**bt\_devreq**(*int s*, *struct bt\_devreq \*r*, *time\_t to*);

*int*\

**bt\_devfilter**(*int s*, *struct bt\_devfilter const \*new*, *struct bt\_devfilter \*old*);

*void*\

**bt\_devfilter\_pkt\_set**(*struct bt\_devfilter \*filter*, *uint8\_t type*);

*void*\

**bt\_devfilter\_pkt\_clt**(*struct bt\_devfilter \*filter*, *uint8\_t type*);

*int*\

**bt\_devfilter\_pkt\_tst**(*struct bt\_devfilter const \*filter*, *uint8\_t type*);

*void*\

**bt\_devfilter\_evt\_set**(*struct bt\_devfilter \*filter*, *uint8\_t event*);

*void*\

**bt\_devfilter\_evt\_clt**(*struct bt\_devfilter \*filter*, *uint8\_t event*);

*int*\

**bt\_devfilter\_evt\_tst**(*struct bt\_devfilter const \*filter*, *uint8\_t event*);

*int*\

**bt\_devinquiry**(*char const \*devname*, *time\_t length*, *int num\_rsp*, *struct bt\_devinquiry \*\*ii*);

*char* *\**\

**bt\_devremote\_name**(*char const \*devname*, *const bdaddr\_t \*remote*, *time\_t to*, *uint16\_t clk\_off*, *uint8\_t ps\_rep\_mode*, *uint8\_t ps\_mode*);

*char* *\**\

**bt\_devremote\_name\_gen**(*char const \*btooth\_devname*, *const bdaddr\_t \*remote*);

*int*\

**bdaddr\_same**(*const bdaddr\_t \*a*, *const bdaddr\_t \*b*);

*int*\

**bdaddr\_any**(*const bdaddr\_t \*a*);

*int*\

**bdaddr\_copy**(*const bdaddr\_t \*dst*, *const bdaddr\_t \*src*);

## DESCRIPTION

The **bt\_gethostent**(), **bt\_gethostbyname**() and **bt\_gethostbyaddr**() functions each return a pointer to an object with the *hostent* structure describing a Bluetooth host referenced by name or by address, respectively.

The *name* argument passed to **bt\_gethostbyname**() should point to a NUL-terminated hostname. The *addr* argument passed to **bt\_gethostbyaddr**() should point to an address which is *len* bytes long, in binary form (i.e., not a Bluetooth BD\_ADDR in human readable ASCII form). The *type* argument specifies the address family of this address and must be set to AF\_BLUETOOTH.

The structure returned contains the information obtained from a line in */etc/bluetooth/hosts* file.

The **bt\_sethostent**() function controls whether */etc/bluetooth/hosts* file should stay open after each call to **bt\_gethostbyname**() or **bt\_gethostbyaddr**(). If the *stayopen* flag is non-zero, the file will not be closed.

The **bt\_endhostent**() function closes the */etc/bluetooth/hosts* file.

The **bt\_getprotoent**(), **bt\_getprotobyname**() and **bt\_getprotobynumber**() functions each return a pointer to an object with the *protoent* structure describing a Bluetooth Protocol Service Multiplexor referenced by name or number, respectively.

The *name* argument passed to **bt\_getprotobyname**() should point to a NUL-terminated Bluetooth Protocol Service Multiplexor name. The *proto* argument passed to **bt\_getprotobynumber**() should have numeric value of the desired Bluetooth Protocol Service Multiplexor.

The structure returned contains the information obtained from a line in */etc/bluetooth/protocols* file.

The **bt\_setprotoent**() function controls whether */etc/bluetooth/protocols* file should stay open after each call to **bt\_getprotobyname**() or **bt\_getprotobynumber**(). If the *stayopen* flag is non-zero, the file will not be closed.

The **bt\_endprotoent**() function closes the */etc/bluetooth/protocols* file.

The **bt\_aton**() routine interprets the specified character string as a Bluetooth address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid.

The routine **bt\_ntoa**() takes a Bluetooth address and places an ASCII string representing the address into the buffer provided. It is up to the caller to ensure that provided buffer has enough space. If no buffer was provided then internal static buffer will be used.

The **bt\_devaddr**() function interprets the specified *devname* string as the address or device name of a Bluetooth device on the local system, and places the device address in the provided *bdaddr*, if any. The function returns 1 if the string was successfully interpreted, or 0 if the string did not match any local device. The **bt\_devname**() function takes a Bluetooth device address and copies the local device name associated with that address into the buffer provided, if any. Caller must ensure that provided buffer is at least HCI\_DEVNAME\_SIZE characters in size. The function returns 1 when the device was found, otherwise 0.

The **bt\_devinfo**() function populates provided *bt\_devinfo* structure with the information about given Bluetooth device. The caller is expected to pass Bluetooth device name in the *devname* field of the passed *bt\_devinfo* structure. The function returns 0 when successful, otherwise -1. The *bt\_devinfo* structure is defined as follows

```
struct bt_devinfo
{
        char            devname[HCI_DEVNAME_SIZE];
        uint32_t        state;
        bdaddr_t        bdaddr;
        uint16_t        _reserved0;
        uint8_t         features[HCI_DEVFEATURES_SIZE];
        /* buffer info */
        uint16_t        _reserved1;
        uint16_t        cmd_free;
        uint16_t        sco_size;
        uint16_t        sco_pkts;
        uint16_t        sco_free;
        uint16_t        acl_size;
        uint16_t        acl_pkts;
        uint16_t        acl_free;
        /* stats */
        uint32_t        cmd_sent;
        uint32_t        evnt_recv;
        uint32_t        acl_recv;
        uint32_t        acl_sent;
        uint32_t        sco_recv;
        uint32_t        sco_sent;
        uint32_t        bytes_recv;
        uint32_t        bytes_sent;
        /* misc/specific */
        uint16_t        link_policy_info;
        uint16_t        packet_type_info;
        uint16_t        role_switch_info;
        uint16_t        debug;
        uint8_t         _padding[20];
};
```

The **bt\_devenum**() function enumerates Bluetooth devices present in the system. For every device found, the function will call provided *cb* callback function which should be of *bt\_devenum\_cb\_t* type. The callback function is passed a HCI socket *s*, fully populated *bt\_devinfo* structure *di* and *arg* argument provided to the **bt\_devenum**(). The callback function can stop enumeration by returning a value that is greater than zero. The function returns number of successfully enumerated devices, or -1 if an error occurred.

The **bt\_devopen**() function opens a Bluetooth device with the given *devname* and returns a connected and bound HCI socket handle. The function returns -1 if an error has occurred.

The **bt\_devclose**() closes the passed HCI socket handle *s*, previously obtained with [bt\_devopen(3)](/bt_devopen/3.md).

The **bt\_devsend**() function sends a Bluetooth HCI command with the given *opcode* to the provided socket *s*, previously obtained with [bt\_devopen(3)](/bt_devopen/3.md). The *opcode* parameter is expected to be in the host byte order. The *param* and *plen* parameters specify command parameters. The **bt\_devsend**() function does not modify the HCI filter on the provided socket *s*. The function returns 0 on success, or -1 if an error occurred.

The **bt\_devrecv**() function receives one Bluetooth HCI packet from the socket *s*, previously obtained with [bt\_devopen(3)](/bt_devopen/3.md). The packet is placed into the provided buffer *buf* of size *size*. The *to* parameter specifies receive timeout in seconds. Infinite timeout can be specified by passing negative value in the *to* parameter. The **bt\_devrecv**() function does not modify the HCI filter on the provided socket *s*. The function returns total number of bytes received, or -1 if an error occurred.

The **bt\_devreq**() function makes a Bluetooth HCI request to the socket *s*, previously obtained with [bt\_devopen(3)](/bt_devopen/3.md). The function will send the specified command and will wait for the specified event, or timeout *to* seconds to occur. The *bt\_devreq* structure is defined as follows

```
struct bt_devreq
{
        uint16_t        opcode;
        uint8_t         event;
        void            *cparam;
        size_t          clen;
        void            *rparam;
        size_t          rlen;
};
```

The *opcode* field specifies the command and is expected to be in the host byte order. The *cparam* and *clen* fields specify command parameters data and command parameters data size respectively. The *event* field specifies which Bluetooth HCI event ID the function should wait for, otherwise it should be set to zero. The HCI Command Complete and Command Status events are enabled by default. The *rparam* and *rlen* parameters specify buffer and buffer size respectively where return parameters should be placed. The **bt\_devreq**() function temporarily modifies filter on the provided HCI socket *s*. The function returns 0 on success, or -1 if an error occurred.

The **bt\_devfilter**() controls the local HCI filter associated with the socket *s*, previously obtained with [bt\_devopen(3)](/bt_devopen/3.md). Filtering can be done on packet types, i.e. ACL, SCO or HCI, command and event packets, and, in addition, on HCI event IDs. Before applying the *new* filter (if provided) the function will try to obtain the current filter from the socket *s* and place it into the *old* parameter (if provided). The function returns 0 on success, or -1 if an error occurred.

The **bt\_devfilter\_pkt\_set**(), **bt\_devfilter\_pkt\_clr**() and **bt\_devfilter\_pkt\_tst**() functions can be used to modify and test the HCI filter *filter*. The *type* parameter specifies HCI packet type.

The **bt\_devfilter\_evt\_set**(), **bt\_devfilter\_evt\_clr**() and **bt\_devfilter\_evt\_tst**() functions can be used to modify and test the HCI event filter *filter*. The *event* parameter specifies HCI event ID.

The **bt\_devinquiry**() function performs Bluetooth inquiry. The *devname* parameter specifies which local Bluetooth device should perform an inquiry. If not specified, i.e. NULL, then first available device will be used. The *length* parameters specifies the total length of an inquiry in seconds. If not specified, i.e. 0, default value will be used. The *num\_rsp* parameter specifies the number of responses that can be received before the inquiry is halted. If not specified, i.e. 0, default value will be used. The *ii* parameter specifies where to place inquiry results. On success, the function will return total number of inquiry results, will allocate, using [calloc(3)](/calloc/3.md), buffer to store all the inquiry results and will return pointer to the allocated buffer in the *ii* parameter. It is up to the caller of the function to dispose of the buffer using [free(3)](/free/3.md) call. The function returns -1 if an error has occurred. The *bt\_devinquiry* structure is defined as follows

```
struct bt_devinquiry {
        bdaddr_t        bdaddr;
        uint8_t         pscan_rep_mode;
        uint8_t         pscan_period_mode;
        uint8_t         dev_class[3];
        uint16_t        clock_offset;
        int8_t          rssi;
        uint8_t         data[240];
};
```

The **bt\_devremote\_name**() function performs Bluetooth Remote Name Request procedure to obtain the user-friendly name of another Bluetooth unit. The *devname* parameter specifies which local Bluetooth device should perform the request. If not specified (NULL), the first available device is used. The *remote* parameter specifies the Bluetooth BD\_ADDR of the remote device to query. The *to* parameter specifies response timeout in seconds. If not specified (0), the default value is taken from the net.bluetooth.hci.command\_timeout [sysctl(8)](/sysctl/8.md) value. The *clk\_off*, *ps\_rep\_mode*, and *ps\_mode* parameters specify Clock\_Offset, Page\_Scan\_Repetition\_Mode, and Page\_Scan\_Mode fields of HCI\_Remote\_Name\_Request respectively. On success, the function returns a pointer to dynamically allocated NUL-terminated string or NULL if an error occurred. It is up to the caller to release returned string using [free(3)](/free/3.md).

The **bt\_devremote\_name\_gen**() function is a shortcut to **bt\_devremote\_name**() that passes generic defaults for *to*, *clk\_off*, *ps\_rep\_mode*, and *ps\_mode* parameters.

The **bdaddr\_same**(), **bdaddr\_any**(), and **bdaddr\_copy**() are handy shorthand Bluetooth address utility functions. The **bdaddr\_same**() function will test if two provided BD\_ADDRs are the same. The **bdaddr\_any**() function will test if provided BD\_ADDR is ANY BD\_ADDR. The **bdaddr\_copy**() function will copy provided *src* BD\_ADDR into provided *dst* BD\_ADDR.

## FILES

- */etc/bluetooth/hosts*

  - */etc/bluetooth/protocols*

  ## EXAMPLES

Print out the hostname associated with a specific BD\_ADDR:

```
const char *bdstr = "00:01:02:03:04:05";
bdaddr_t bd;
struct hostent *hp;
if (!bt_aton(bdstr, &bd))
	errx(1, "can't parse BD_ADDR %s", bdstr);
if ((hp = bt_gethostbyaddr((const char *)&bd,
    sizeof(bd), AF_BLUETOOTH)) == NULL)
	errx(1, "no name associated with %s", bdstr);
printf("name associated with %s is %s\n", bdstr, hp->h_name);
```

## DIAGNOSTICS

Error return status from **bt\_gethostent**(), **bt\_gethostbyname**() and **bt\_gethostbyaddr**() is indicated by return of a NULL pointer. The external integer *h\_errno* may then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine [herror(3)](/herror/3.md) can be used to print an error message describing the failure. If its argument *string* is non-NULL, it is printed, followed by a colon and a space. The error message is printed with a trailing newline.

The variable *h\_errno* can have the following values:

- HOST\_NOT\_FOUND

  No such host is known.

- NO\_RECOVERY

  Some unexpected server failure was encountered. This is a non-recoverable error.

The **bt\_getprotoent**(), **bt\_getprotobyname**() and **bt\_getprotobynumber**() return NULL on EOF or error.

## SEE ALSO

[gethostbyaddr(3)](/gethostbyaddr/3.md), [gethostbyname(3)](/gethostbyname/3.md), [getprotobyname(3)](/getprotobyname/3.md), [getprotobynumber(3)](/getprotobynumber/3.md), [herror(3)](/herror/3.md), [inet\_aton(3)](/inet_aton/3.md), [inet\_ntoa(3)](/inet_ntoa/3.md), [ng\_hci(4)](/ng_hci/4.md)

## CAVEAT

The **bt\_gethostent**() function reads the next line of */etc/bluetooth/hosts*, opening the file if necessary.

The **bt\_sethostent**() function opens and/or rewinds the */etc/bluetooth/hosts* file.

The **bt\_getprotoent**() function reads the next line of */etc/bluetooth/protocols*, opening the file if necessary.

The **bt\_setprotoent**() function opens and/or rewinds the */etc/bluetooth/protocols* file.

The **bt\_devenum**() function enumerates up to HCI\_DEVMAX Bluetooth devices. During enumeration the **bt\_devenum**() function uses the same HCI socket. The function guarantees that the socket, passed to the callback function, will be bound and connected to the Bluetooth device being enumerated.

## AUTHORS

Maksim Yevmenkin ⟨*m\_evmenkin@yahoo.com*⟩

## BUGS

Some of those functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it.