--- name: "ng_btsocket" section: "4" platform: "linux" package: "freebsd-manpages" version: "6.0-5" release: "Debian 4.0 (Etch)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/ng_btsocket" --- # ng\_btsocket(4) Bluetooth sockets layer ## NAME **ng\_btsocket** – Bluetooth sockets layer ## SYNOPSIS **#include \** **#include \** **#include \** **#include \** **#include \** **#include \** ## DESCRIPTION The **ng\_btsocket** module implements three Netgraph node types. Each type in its turn implements one protocol within PF\_BLUETOOTH domain. ## Dv BLUETOOTH\_PROTO\_HCI Sh protocol ### Dv SOCK\_RAW Ss HCI sockets Implemented by **btsock\_hci\_raw** Netgraph type. Raw HCI sockets allow sending of raw HCI command datagrams only to correspondents named in [send(2)](/send/2.md) calls. Raw HCI datagrams (HCI commands, events and data) are generally received with [recvfrom(2)](/recvfrom/2.md), which returns the next datagram with its return address. Raw HCI sockets can also be used to control HCI nodes. The Bluetooth raw HCI socket address is defined as follows: ``` /* Bluetooth version of struct sockaddr for raw HCI sockets */ struct sockaddr_hci { u_char hci_len; /* total length */ u_char hci_family; /* address family */ char hci_node[16]; /* HCI node name */ }; ``` Raw HCI sockets support number of [ioctl(2)](/ioctl/2.md) requests such as: - SIOC\_HCI\_RAW\_NODE\_GET\_STATE Returns current state for the HCI node. - SIOC\_HCI\_RAW\_NODE\_INIT Turn on “inited” bit for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_DEBUG Returns current debug level for the HCI node. - SIOC\_HCI\_RAW\_NODE\_SET\_DEBUG Sets current debug level for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_BUFFER Returns current state of data buffers for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_BDADDR Returns BD\_ADDR for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_FEATURES Returns the list of features supported by hardware for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_STAT Returns various statistic counters for the HCI node. - SIOC\_HCI\_RAW\_NODE\_RESET\_STAT Resets all statistic counters for the HCI node to zero. - SIOC\_HCI\_RAW\_NODE\_FLUSH\_NEIGHBOR\_CACHE Remove all neighbor cache entries for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_NEIGHBOR\_CACHE Returns content of the neighbor cache for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_CON\_LIST Returns list of active baseband connections (i.e., ACL and SCO links) for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_LINK\_POLICY\_MASK Returns current link policy settings mask for the HCI node. - SIOC\_HCI\_RAW\_NODE\_SET\_LINK\_POLICY\_MASK Sets current link policy settings mask for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_PACKET\_MASK Returns current packet mask for the HCI node. - SIOC\_HCI\_RAW\_NODE\_SET\_PACKET\_MASK Sets current packet mask for the HCI node. - SIOC\_HCI\_RAW\_NODE\_GET\_ROLE\_SWITCH Returns current value of the role switch parameter for the HCI node. - SIOC\_HCI\_RAW\_NODE\_SET\_ROLE\_SWITCH Sets new value of the role switch parameter for the HCI node. The *net.bluetooth.hci.sockets.raw.ioctl\_timeout* variable, that can be examined and set via [sysctl(8)](/sysctl/8.md), controls the control request timeout (in seconds) for raw HCI sockets. Raw HCI sockets support filters. The application can filter certain HCI datagram types. For HCI event datagrams the application can set additional filter. The raw HCI socket filter defined as follows: ``` /* * Raw HCI socket filter. * * For packet mask use (1 << (HCI packet indicator - 1)) * For event mask use (1 << (Event - 1)) */ struct ng_btsocket_hci_raw_filter { bitstr_t bit_decl(packet_mask, 32); bitstr_t bit_decl(event_mask, (NG_HCI_EVENT_MASK_SIZE * 8)); }; ``` The SO\_HCI\_RAW\_FILTER option defined at SOL\_HCI\_RAW level can be used to obtain via [getsockopt(2)](/getsockopt/2.md) or change via [setsockopt(2)](/setsockopt/2.md) raw HCI socket's filter. ## Dv BLUETOOTH\_PROTO\_L2CAP Sh protocol The Bluetooth L2CAP socket address is defined as follows: ``` /* Bluetooth version of struct sockaddr for L2CAP sockets */ struct sockaddr_l2cap { u_char l2cap_len; /* total length */ u_char l2cap_family; /* address family */ u_int16_t l2cap_psm; /* Protocol/Service Multiplexor */ bdaddr_t l2cap_bdaddr; /* address */ }; ``` ### Dv SOCK\_RAW Ss L2CAP sockets Implemented by **btsock\_l2c\_raw** Netgraph type. Raw L2CAP sockets do not provide access to raw L2CAP datagrams. These sockets used to control L2CAP nodes and to issue special L2CAP requests such as ECHO\_REQUEST and GET\_INFO request. Raw L2CAP sockets support number of [ioctl(2)](/ioctl/2.md) requests such as: - SIOC\_L2CAP\_NODE\_GET\_FLAGS Returns current state for the L2CAP node. - SIOC\_L2CAP\_NODE\_GET\_DEBUG Returns current debug level for the L2CAP node. - SIOC\_L2CAP\_NODE\_SET\_DEBUG Sets current debug level for the L2CAP node. - SIOC\_L2CAP\_NODE\_GET\_CON\_LIST Returns list of active baseband connections (i.e., ACL links) for the L2CAP node. - SIOC\_L2CAP\_NODE\_GET\_CHAN\_LIST Returns list of active channels for the L2CAP node. - SIOC\_L2CAP\_NODE\_GET\_AUTO\_DISCON\_TIMO Returns current value of the auto disconnect timeout for the L2CAP node. - SIOC\_L2CAP\_NODE\_SET\_AUTO\_DISCON\_TIMO Sets current value of the auto disconnect timeout for the L2CAP node. - SIOC\_L2CAP\_L2CA\_PING Issues L2CAP ECHO\_REQUEST. - SIOC\_L2CAP\_L2CA\_GET\_INFO Issues L2CAP GET\_INFO request. The *net.bluetooth.l2cap.sockets.raw.ioctl\_timeout* variable, that can be examined and set via [sysctl(8)](/sysctl/8.md), controls the control request timeout (in seconds) for raw L2CAP sockets. ### Dv SOCK\_SEQPACKET Ss L2CAP sockets Implemented by **btsock\_l2c** Netgraph type. L2CAP sockets are either “active” or “passive”. Active sockets initiate connections to passive sockets. By default, L2CAP sockets are created active; to create a passive socket, the [listen(2)](/listen/2.md) system call must be used after binding the socket with the [bind(2)](/bind/2.md) system call. Only passive sockets may use the [accept(2)](/accept/2.md) call to accept incoming connections. Only active sockets may use the [connect(2)](/connect/2.md) call to initiate connections. L2CAP sockets support “wildcard addressing”. In this case, socket must be bound to NG\_HCI\_BDADDR\_ANY address. Note that PSM (Protocol/Service Multiplexor) field is always required. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the Bluetooth device through which packets are being transmitted and received, and PSM (Protocol/Service Multiplexor). L2CAP sockets support number of options defined at SOL\_L2CAP level which can be set with [setsockopt(2)](/setsockopt/2.md) and tested with [getsockopt(2)](/getsockopt/2.md): - SO\_L2CAP\_IMTU Get (set) maximum payload size the local socket is capable of accepting. - SO\_L2CAP\_OMTU Get maximum payload size the remote socket is capable of accepting. - SO\_L2CAP\_IFLOW Get incoming flow specification for the socket. Not implemented. - SO\_L2CAP\_OFLOW Get (set) outgoing flow specification for the socket. Not implemented. - SO\_L2CAP\_FLUSH Get (set) value of the flush timeout. Not implemented. ## Dv BLUETOOTH\_PROTO\_RFCOMM Sh protocol The Bluetooth RFCOMM socket address is defined as follows: ``` /* Bluetooth version of struct sockaddr for RFCOMM sockets */ struct sockaddr_rfcomm { u_char rfcomm_len; /* total length */ u_char rfcomm_family; /* address family */ bdaddr_t rfcomm_bdaddr; /* address */ u_int8_t rfcomm_channel; /* channel */ }; ``` ### Dv SOCK\_STREAM Ss RFCOMM sockets Note that RFCOMM sockets do not have associated Netgraph node type. RFCOMM sockets are implemented as additional layer on top of L2CAP sockets. RFCOMM sockets are either “active” or “passive”. Active sockets initiate connections to passive sockets. By default, RFCOMM sockets are created active; to create a passive socket, the [listen(2)](/listen/2.md) system call must be used after binding the socket with the [bind(2)](/bind/2.md) system call. Only passive sockets may use the [accept(2)](/accept/2.md) call to accept incoming connections. Only active sockets may use the [connect(2)](/connect/2.md) call to initiate connections. RFCOMM sockets support “wildcard addressing”. In this case, socket must be bound to NG\_HCI\_BDADDR\_ANY address. Note that RFCOMM channel field is always required. Once a connection has been established, the socket's address is fixed by the peer entity's location. The address assigned to the socket is the address associated with the Bluetooth device through which packets are being transmitted and received, and RFCOMM channel. The following options, which can be tested with [getsockopt(2)](/getsockopt/2.md) call, are defined at SOL\_RFCOMM level for RFCOMM sockets: - SO\_RFCOMM\_MTU Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM channel. Note that application still can write/read bigger chunks to/from the socket. - SO\_RFCOMM\_FC\_INFO Return the flow control information for the underlying RFCOMM channel. The *net.bluetooth.rfcomm.sockets.stream.timeout* variable, that can be examined and set via [sysctl(8)](/sysctl/8.md), controls the connection timeout (in seconds) for RFCOMM sockets. ## HOOKS These node types support hooks with arbitrary names (as long as they are unique) and always accept hook connection requests. ## NETGRAPH CONTROL MESSAGES These node types support the generic control messages. ## SHUTDOWN These nodes are persistent and cannot be shut down. ## SEE ALSO [btsockstat(1)](/btsockstat/1.md), [socket(2)](/socket/2.md), [netgraph(4)](/netgraph/4.md), [ng\_bluetooth(4)](/ng_bluetooth/4.md), [ng\_hci(4)](/ng_hci/4.md), [ng\_l2cap(4)](/ng_l2cap/4.md), [ngctl(8)](/ngctl/8.md), [sysctl(8)](/sysctl/8.md) ## HISTORY The **ng\_btsocket** module was implemented in FreeBSD 5.0. ## AUTHORS Maksim Yevmenkin ⟨m\_evmenkin@yahoo.com⟩ ## BUGS Most likely. Please report if found.