NG_BTSOCKET(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

🦋 NG_BTSOCKET(4) — ng_btsocket(4) — Bluetooth sockets layer (Kernel Interfaces Manual) 🦋

✨ NAME ✨

ng_btsocket — Bluetooth sockets layer

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <sys/socket.h>
#include <sys/bitstring.h>
#include <netgraph/bluetooth/include/ng_hci.h>
#include <netgraph/bluetooth/include/ng_l2cap.h>
#include <netgraph/bluetooth/include/ng_btsocket.h>

💖 DESCRIPTION 💖

okay so bestie, the ng_btsocket module implements three Netgraph node types. Each type in its turn implements one protocol within PF_BLUETOOTH domain. literally three node types doing their own protocol thing in the PF_BLUETOOTH domain, slay 💅

🔥 BLUETOOTH_PROTO_HCI protocol 🔥

📡 SOCK_RAW 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) calls. Raw HCI datagrams (HCI commands, events and data) are generally received with recvfrom(2), which returns the next datagram with its return address. Raw HCI sockets can also be used to control HCI nodes. no cap, they're giving control-panel energy.

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[32]; /* address (size == NG_NODESIZ ) */
             };

Raw HCI sockets support a number of ioctl(2) requests such as:

  • SIOC_HCI_RAW_NODE_GET_STATE — grabs the current state for the HCI node.
  • SIOC_HCI_RAW_NODE_INIT — turns on the “inited” bit for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_DEBUG — hands you the current debug level for the HCI node.
  • SIOC_HCI_RAW_NODE_SET_DEBUG — sets the current debug level for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_BUFFER — gives you the current state of the data buffers for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_BDADDR — returns the 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 the 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 — removes all neighbor cache entries for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_NEIGHBOR_CACHE — returns the content of the neighbor cache for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_CON_LIST — returns the list of active baseband connections (i.e., ACL and SCO links) for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_LINK_POLICY_MASK — returns the current link policy settings mask for the HCI node.
  • SIOC_HCI_RAW_NODE_SET_LINK_POLICY_MASK — sets the current link policy settings mask for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_PACKET_MASK — returns the current packet mask for the HCI node.
  • SIOC_HCI_RAW_NODE_SET_PACKET_MASK — sets the current packet mask for the HCI node.
  • SIOC_HCI_RAW_NODE_GET_ROLE_SWITCH — returns the current value of the role switch parameter for the HCI node.
  • SIOC_HCI_RAW_NODE_SET_ROLE_SWITCH — sets the 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), controls the control request timeout (in seconds) for raw HCI sockets. set it and forget it, but like, intentionally.

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 is 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) or change via setsockopt(2) raw HCI socket's filter. filter game strong 💅

💙 BLUETOOTH_PROTO_L2CAP 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 */
                     uint16_t  l2cap_psm;    /* Protocol/Service Multiplexor */
                     bdaddr_t  l2cap_bdaddr; /* address */
             };

🧵 SOCK_RAW 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. note: no raw L2CAP datagrams, this is a control/special-request situation.

Raw L2CAP sockets support a number of ioctl(2) requests such as:

  • SIOC_L2CAP_NODE_GET_FLAGS — returns the current state for the L2CAP node.
  • SIOC_L2CAP_NODE_GET_DEBUG — hands back the current debug level for the L2CAP node.
  • SIOC_L2CAP_NODE_SET_DEBUG — sets the current debug level for the L2CAP node.
  • SIOC_L2CAP_NODE_GET_CON_LIST — returns the list of active baseband connections (i.e., ACL links) for the L2CAP node.
  • SIOC_L2CAP_NODE_GET_CHAN_LIST — returns the list of active channels for the L2CAP node.
  • SIOC_L2CAP_NODE_GET_AUTO_DISCON_TIMO — returns the current value of the auto disconnect timeout for the L2CAP node.
  • SIOC_L2CAP_NODE_SET_AUTO_DISCON_TIMO — sets the current value of the auto disconnect timeout for the L2CAP node.
  • SIOC_L2CAP_L2CA_PING — issues an L2CAP ECHO_REQUEST.
  • SIOC_L2CAP_L2CA_GET_INFO — issues an L2CAP GET_INFO request.

The net.bluetooth.l2cap.sockets.raw.ioctl_timeout variable, that can be examined and set via sysctl(8), controls the control request timeout (in seconds) for raw L2CAP sockets.

🎧 SOCK_SEQPACKET 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) system call must be used after binding the socket with the bind(2) system call. Only passive sockets may use the accept(2) call to accept incoming connections. Only active sockets may use the connect(2) call to initiate connections. active/passive lore, periodt.

L2CAP sockets support “wildcard addressing”. In this case, the 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). the PSM is always required, iykyk.

L2CAP sockets support a number of options defined at SOL_L2CAP level which can be set with setsockopt(2) and tested with getsockopt(2):

  • SO_L2CAP_IMTU — get (set) the maximum payload size the local socket is capable of accepting.
  • SO_L2CAP_OMTU — get the maximum payload size the remote socket is capable of accepting.
  • SO_L2CAP_IFLOW — get the incoming flow specification for the socket. Not implemented.
  • SO_L2CAP_OFLOW — get (set) the outgoing flow specification for the socket. Not implemented.
  • SO_L2CAP_FLUSH — get (set) the value of the flush timeout. Not implemented.

💜 BLUETOOTH_PROTO_RFCOMM 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 */
                     uint8_t  rfcomm_channel; /* channel */
             };

🎀 SOCK_STREAM 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) system call must be used after binding the socket with the bind(2) system call. Only passive sockets may use the accept(2) call to accept incoming connections. Only active sockets may use the connect(2) call to initiate connections. no Netgraph node type for RFCOMM, it's just extra layer energy on top of L2CAP.

RFCOMM sockets support “wildcard addressing”. In this case, the 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. RFCOMM channel always required, fr fr.

The following options, which can be tested with getsockopt(2) 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), 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. unique names only, bestie.

⭐ NETGRAPH CONTROL MESSAGES ⭐

These node types support the generic control messages.

🛑 SHUTDOWN 🛑

These nodes are persistent and cannot be shut down. literally cannot be shut down, they're persistent.

👀 SEE ALSO 👀

btsockstat(1), socket(2), netgraph(4), ng_bluetooth(4), ng_hci(4), ng_l2cap(4), ngctl(8), sysctl(8)

🕰️ HISTORY 🕰️

The ng_btsocket module was implemented in FreeBSD 5.0. ancient icon behavior.

👑 AUTHORS 👑

Maksim Yevmenkin <m_evmenkin@yahoo.com>

💀 BUGS 💀

Most likely. Please report if found. at least they're honest, bestie 😭

xoxo, Debian — November 13, 2012 🎀

📦 where this page comes from