l2cap(7) Linux System Administration l2cap(7) # [Name](#Name) l2cap - L2CAP protocol # [SYNOPSIS](#SYNOPSIS) ``` #include #include #include l2cap_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_L2CAP); ``` # [DESCRIPTION](#DESCRIPTION) L2CAP is a protocol that provides an interface for higher-level protocols to send and receive data over a Bluetooth connection. L2CAP sits on top of the Bluetooth Host Controller Interface (HCI) and provides a set of channels that can be used by higher-level protocols to transmit data. L2CAP provides a number of services to higher-level protocols, including segmentation and reassembly of large data packets and flow control to prevent overloading of the receiver. L2CAP also supports multiple channels per connection, allowing for concurrent data transmission using different protocols. # [SOCKET ADDRESS](#SOCKET_ADDRESS) ``` struct sockaddr_l2 { sa_family_t l2_family; unsigned short l2_psm; bdaddr_t l2_bdaddr; unsigned short l2_cid; uint8_t l2_bdaddr_type; }; ``` Example: ``` struct sockaddr_l2 addr; memset(&addr, 0, sizeof(addr)); addr.l2_family = AF_BLUETOOTH; bacpy(&addr.l2_bdaddr, bdaddr); if (cid) addr.l2_cid = htobs(cid); else addr.l2_psm = htobs(psm); addr.l2_bdaddr_type = bdaddr_type; ``` # [SOCKET OPTIONS (SOL\_BLUETOOTH)](#SOCKET_OPTIONS_%28SOL_BLUETOOTH%29) The socket options listed below can be set by using [**setsockopt(2)**](/man/os/bluez/setsockopt.2) and read with [**getsockopt(2)**](/man/os/bluez/getsockopt.2) with the socket level set to SOL\_BLUETOOTH. ## [BT\_SECURITY (since Linux 2.6.30)](#BT_SECURITY_%28since_Linux_2.6.30%29) Channel security level, possible values: Value Security Level Link Key Type Encryption **BT\_SECURITY\_SDP** 0 (SDP Only) None Not required **BT\_SECURITY\_LOW** 1 (Low) Unauthenticated Not required **BT\_SECURITY\_MEDIUM** 2 (Medium - default) Unauthenticated Desired **BT\_SECURITY\_HIGH** 3 (High) Authenticated Required **BT\_SECURITY\_FIPS** (since Linux 3.15) 4 (Secure Only) Authenticated (P-256 based Secure Simple Pairing and Secure Authentication) Required Example: ``` int level = BT_SECURITY_HIGH; int err = setsockopt(l2cap_socket, SOL_BLUETOOTH, BT_SECURITY, &level, sizeof(level)); if (err == -1) { perror("setsockopt"); return 1; } ``` ## [BT\_DEFER\_SETUP (since Linux 2.6.30)](#BT_DEFER_SETUP_%28since_Linux_2.6.30%29) Channel defer connection setup, this control if the connection procedure needs to be authorized by userspace before responding which allows authorization at profile level, possible values: Value Description Authorization **0** Disable (default) Not required **1** Enable Required Example: ``` int defer_setup = 1; int err = setsockopt(l2cap_socket, SOL_BLUETOOTH, BT_DEFER_SETUP, &defer_setup, sizeof(defer_setup)); if (err == -1) { perror("setsockopt"); return err; } err = listen(l2cap_socket, 5); if (err) { perror("listen"); return err; } struct sockaddr_l2 remote_addr = {0}; socklen_t addr_len = sizeof(remote_addr); int new_socket = accept(l2cap_socket, (struct sockaddr*)&remote_addr, &addr_len); if (new_socket < 0) { perror("accept"); return new_socket; } /* To complete the connection setup of new_socket read 1 byte */ char c; struct pollfd pfd; memset(&pfd, 0, sizeof(pfd)); pfd.fd = new_socket; pfd.events = POLLOUT; err = poll(&pfd, 1, 0); if (err) { perror("poll"); return err; } if (!(pfd.revents & POLLOUT)) { err = read(sk, &c, 1); if (err < 0) { perror("read"); return err; } } ``` ## [BT\_FLUSHABLE (since Linux 2.6.39)](#BT_FLUSHABLE_%28since_Linux_2.6.39%29) Channel flushable flag, this control if the channel data can be flushed or not, possible values: Define Value Description **BT\_FLUSHABLE\_OFF** 0x00 (default) Do not flush data **BT\_FLUSHABLE\_ON** 0x01 Flush data ## [BT\_POWER (since Linux 3.1)](#BT_POWER_%28since_Linux_3.1%29) Channel power policy, this control if the channel shall force exit of sniff mode or not, possible values: Define Value Description **BT\_POWER\_FORCE\_ACTIVE\_OFF** 0x00 Don't force exit of sniff mode **BT\_POWER\_FORCE\_ACTIVE\_ON** 0x01 (default) Force exit of sniff mode ## [BT\_CHANNEL\_POLICY (since Linux 3.10)](#BT_CHANNEL_POLICY_%28since_Linux_3.10%29) High-speed (AMP) channel policy, possible values: Define Value Description **BT\_CHANNEL\_POLICY\_BREDR\_ONLY** 0 (default) BR/EDR only **BT\_CHANNEL\_POLICY\_BREDR\_PREFERRED** 1 BR/EDR Preferred **BT\_CHANNEL\_POLICY\_BREDR\_PREFERRED** 2 AMP Preferred ## [BT\_PHY (since Linux 5.10)](#BT_PHY_%28since_Linux_5.10%29) Channel supported PHY(s), possible values: Define Value Description **BT\_PHY\_BR\_1M\_1SLOT** BIT 0 BR 1Mbps 1SLOT **BT\_PHY\_BR\_1M\_3SLOT** BIT 1 BR 1Mbps 3SLOT **BT\_PHY\_BR\_1M\_5SLOT** BIT 2 BR 1Mbps 5SLOT **BT\_PHY\_BR\_2M\_1SLOT** BIT 3 EDR 2Mbps 1SLOT **BT\_PHY\_BR\_2M\_3SLOT** BIT 4 EDR 2Mbps 3SLOT **BT\_PHY\_BR\_2M\_5SLOT** BIT 5 EDR 2Mbps 5SLOT **BT\_PHY\_BR\_3M\_1SLOT** BIT 6 EDR 3Mbps 1SLOT **BT\_PHY\_BR\_3M\_3SLOT** BIT 7 EDR 3Mbps 3SLOT **BT\_PHY\_BR\_3M\_5SLOT** BIT 8 EDR 3Mbps 5SLOT **BT\_PHY\_LE\_1M\_TX** BIT 9 LE 1Mbps TX **BT\_PHY\_LE\_1M\_RX** BIT 10 LE 1Mbps RX **BT\_PHY\_LE\_2M\_TX** BIT 11 LE 2Mbps TX **BT\_PHY\_LE\_2M\_RX** BIT 12 LE 2Mbps RX **BT\_PHY\_LE\_CODED\_TX** BIT 13 LE Coded TX **BT\_PHY\_LE\_CODED\_RX** BIT 14 LE Coded RX ## [BT\_MODE (since Linux 5.10)](#BT_MODE_%28since_Linux_5.10%29) Channel Mode, possible values: Define Value Description Link **BT\_MODE\_BASIC** 0x00 (default) Basic mode Any **BT\_MODE\_ERTM** 0x01 Enhanced Retransmission mode BR/EDR **BT\_MODE\_STREAM** 0x02 Stream mode BR/EDR **BT\_MODE\_LE\_FLOWCTL** 0x03 Credit based flow control mode LE **BT\_MODE\_EXT\_FLOWCTL** 0x04 Extended Credit based flow control mode Any # [SOCKET OPTIONS (SOL\_SOCKET)](#SOCKET_OPTIONS_%28SOL_SOCKET%29) **SOL\_SOCKET** level socket options that modify generic socket features (**SO\_SNDBUF**, **SO\_RCVBUF**, etc.) have their usual meaning, see [**socket(7)**](/man/os/bluez/socket.7). The **SOL\_SOCKET** level L2CAP socket options that have Bluetooth-specific handling in kernel are listed below. ## [SO\_TIMESTAMPING, SO\_TIMESTAMP, SO\_TIMESTAMPNS](#SO_TIMESTAMPING,_SO_TIMESTAMP,_SO_TIMESTAMPNS) See <https://docs.kernel.org/networking/timestamping.html> For L2CAP sockets, software RX timestamps are supported. Software TX timestamps (SOF\_TIMESTAMPING\_TX\_SOFTWARE, SOF\_TIMESTAMPING\_TX\_COMPLETION) are supported since Linux 6.15. The software RX timestamp is the time when the kernel received the packet from the controller driver. The **SCM\_TSTAMP\_SND** timestamp is emitted when packet is sent to the controller driver. The **SCM\_TSTAMP\_COMPLETION** timestamp is emitted when controller reports the packet completed. Other TX timestamp types are not supported. You can use **SIOCETHTOOL** to query supported flags. The timestamps are in **CLOCK\_REALTIME** time. Example (Enable RX timestamping): ``` int flags = SOF_TIMESTAMPING_SOFTWARE | SOF_TIMESTAMPING_RX_SOFTWARE; setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags)); ``` Example (Read packet and its RX timestamp): ``` char data_buf[256]; union { char buf[CMSG_SPACE(sizeof(struct scm_timestamping))]; struct cmsghdr align; } control; struct iovec data = { .iov_base = data_buf, .iov_len = sizeof(data_buf), }; struct msghdr msg = { .msg_iov = &data, .msg_iovlen = 1, .msg_control = control.buf, .msg_controllen = sizeof(control.buf), }; struct scm_timestamping tss; res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT); if (res < 0) goto error; for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) { if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING) memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss)); } tstamp_clock_realtime = tss.ts[0]; ``` Example (Enable TX timestamping): ``` int flags = SOF_TIMESTAMPING_SOFTWARE | SOF_TIMESTAMPING_TX_SOFTWARE | SOF_TIMESTAMPING_TX_COMPLETION | SOF_TIMESTAMPING_OPT_ID; setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags)); ``` Example (Read TX timestamps): ``` union { char buf[2 * CMSG_SPACE(sizeof(struct scm_timestamping))]; struct cmsghdr align; } control; struct iovec data = { .iov_base = NULL, .iov_len = 0 }; struct msghdr msg = { .msg_iov = &data, .msg_iovlen = 1, .msg_control = control.buf, .msg_controllen = sizeof(control.buf), }; struct cmsghdr *cmsg; struct scm_timestamping tss; struct sock_extended_err serr; int res; res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT); if (res < 0) goto error; for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) { if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING) memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss)); else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR) memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr)); } tstamp_clock_realtime = tss.ts[0]; tstamp_type = serr->ee_info; /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */ tstamp_seqnum = serr->ee_data; ``` # [IOCTLS](#IOCTLS) The following ioctls with operation specific for L2CAP sockets are available. ## [SIOCETHTOOL (since Linux 6.16-rc1)](#SIOCETHTOOL_%28since_Linux_6.16) Supports only command *ETHTOOL\_GET\_TS\_INFO*, which may be used to query supported *SOF\_TIMESTAMPING\_\** flags. The *SOF\_TIMESTAMPING\_OPT\_\** flags are always available as applicable. Example: ``` #include #include #include #include #include ... struct ifreq ifr = {}; struct ethtool_ts_info cmd = {}; int sk; snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0"); ifr.ifr_data = (void *)&cmd; cmd.cmd = ETHTOOL_GET_TS_INFO; sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_L2CAP); if (sk < 0) goto error; if (ioctl(sk, SIOCETHTOOL, &ifr)) goto error; sof_available = cmd.so_timestamping; ``` # [RESOURCES](#RESOURCES) <http://www.bluez.org> # [REPORTING BUGS](#REPORTING_BUGS) <linux-bluetooth@vger.kernel.org> # [SEE ALSO](#SEE_ALSO) [socket(7)](/man/os/bluez/socket.7), [l2test(1)](/man/os/bluez/l2test.1) # [Copyright](#Copyright) Free use of this software is granted under the terms of the GNU Lesser General Public Licenses (LGPL). May 2024 BlueZ --- Document: l2cap(7) from bluez 5.87-r4 (Chainguard OS) Source: https://github.com/bluez/bluez