l2cap - Man Page

L2CAP protocol

Synopsis

#include <sys/socket.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/l2cap.h>

l2cap_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_L2CAP);

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

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

The socket options listed below can be set by using setsockopt(2) and read with getsockopt(2) with the socket level set to SOL_BLUETOOTH.

BT_SECURITY (since Linux 2.6.30)

Channel security level, possible values:

ValueSecurity LevelLink Key TypeEncryption
BT_SECURITY_SDP0 (SDP Only)NoneNot required
BT_SECURITY_LOW1 (Low)UnauthenticatedNot required
BT_SECURITY_MEDIUM2 (Medium - default)UnauthenticatedDesired
BT_SECURITY_HIGH3 (High)AuthenticatedRequired
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)

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:

ValueDescriptionAuthorization
0Disable (default)Not required
1EnableRequired

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)

Channel flushable flag, this control if the channel data can be flushed or not, possible values:

DefineValueDescription
BT_FLUSHABLE_OFF0x00 (default)Do not flush data
BT_FLUSHABLE_ON0x01Flush data

BT_POWER (since Linux 3.1)

Channel power policy, this control if the channel shall force exit of sniff mode or not, possible values:

DefineValueDescription
BT_POWER_FORCE_ACTIVE_OFF0x00 (default)Don't force exit of sniff mode
BT_POWER_FORCE_ACTIVE_ON0x01Force exit of sniff mode

BT_CHANNEL_POLICY (since Linux 3.10)

High-speed (AMP) channel policy, possible values:

DefineValueDescription
BT_CHANNEL_POLICY_BREDR_ONLY0 (default)BR/EDR only
BT_CHANNEL_POLICY_BREDR_PREFERRED1BR/EDR Preferred
BT_CHANNEL_POLICY_BREDR_PREFERRED2AMP Preferred

BT_PHY (since Linux 5.10)

Channel supported PHY(s), possible values:

DefineValueDescription
BT_PHY_BR_1M_1SLOTBIT 0BR 1Mbps 1SLOT
BT_PHY_BR_1M_3SLOTBIT 1BR 1Mbps 3SLOT
BT_PHY_BR_1M_5SLOTBIT 2BR 1Mbps 5SLOT
BT_PHY_BR_2M_1SLOTBIT 3EDR 2Mbps 1SLOT
BT_PHY_BR_2M_3SLOTBIT 4EDR 2Mbps 3SLOT
BT_PHY_BR_2M_5SLOTBIT 5EDR 2Mbps 5SLOT
BT_PHY_BR_3M_1SLOTBIT 6EDR 3Mbps 1SLOT
BT_PHY_BR_3M_3SLOTBIT 7EDR 3Mbps 3SLOT
BT_PHY_BR_3M_5SLOTBIT 8EDR 3Mbps 5SLOT
BT_PHY_LE_1M_TXBIT 9LE 1Mbps TX
BT_PHY_LE_1M_RXBIT 10LE 1Mbps RX
BT_PHY_LE_2M_TXBIT 11LE 2Mbps TX
BT_PHY_LE_2M_RXBIT 12LE 2Mbps RX
BT_PHY_LE_CODED_TXBIT 13LE Coded TX
BT_PHY_LE_CODED_RXBIT 14LE Coded RX

BT_MODE (since Linux 5.10)

Channel Mode, possible values:

DefineValueDescriptionLink
BT_MODE_BASIC0x00 (default)Basic modeAny
BT_MODE_ERTM0x01Enhanced Retransmission modeBR/EDR
BT_MODE_STREAM0x02Stream modeBR/EDR
BT_MODE_LE_FLOWCTL0x03Credit based flow control modeLE
BT_MODE_EXT_FLOWCTL0x04Extended Credit based flow control modeAny

Resources

<http://www.bluez.org>

Reporting Bugs

<linux-bluetooth@vger.kernel.org>

See Also

socket(7), l2test(1)

Info

May 2024 BlueZ Linux System Administration