oracular (7) l2cap.7.gz

Provided by: libbluetooth-dev_5.77-0ubuntu2_amd64 bug

NAME

       l2cap - 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:

            ┌───────────────────┬─────────────────────┬─────────────────────┬──────────────┐
            │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     - │ Unauthenticated     │ Desired      │
            │                   │ default)            │                     │              │
            ├───────────────────┼─────────────────────┼─────────────────────┼──────────────┤
            │BT_SECURITY_HIGH   │ 3 (High)            │ Authenticated       │ Required     │
            ├───────────────────┼─────────────────────┼─────────────────────┼──────────────┤
            │BT_SECURITY_FIPS   │ 4 (Secure Only)     │ Authenticated       │ Required     │
            │(since Linux 3.15) │                     │ (P-256 based Secure │              │
            │                   │                     │ Simple Pairing  and │              │
            │                   │                     │ Secure              │              │
            │                   │                     │ Authentication)     │              │
            └───────────────────┴─────────────────────┴─────────────────────┴──────────────┘
       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:

                              ┌──────┬───────────────────┬───────────────┐
                              │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)
       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)
       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 (default) │ Don't   force   exit  of │
                │                          │                │ sniff mode               │
                ├──────────────────────────┼────────────────┼──────────────────────────┤
                │BT_POWER_FORCE_ACTIVE_ON  │ 0x01           │ Force exit of sniff mode │
                └──────────────────────────┴────────────────┴──────────────────────────┘
   BT_CHANNEL_POLICY (since Linux 3.10)
       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)
       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)
       Channel Mode, possible values:

                 ┌────────────────────┬────────────────┬─────────────────────┬────────┐
                 │Define              │ Value          │ Description         │ Link   │
                 ├────────────────────┼────────────────┼─────────────────────┼────────┤
                 │BT_MODE_BASIC       │ 0x00 (default) │ Basic mode          │ Any    │
                 ├────────────────────┼────────────────┼─────────────────────┼────────┤
                 │BT_MODE_ERTM        │ 0x01           │ Enhanced            │ BR/EDR │
                 │                    │                │ Retransmission mode │        │
                 ├────────────────────┼────────────────┼─────────────────────┼────────┤
                 │BT_MODE_STREAM      │ 0x02           │ Stream mode         │ BR/EDR │
                 ├────────────────────┼────────────────┼─────────────────────┼────────┤
                 │BT_MODE_LE_FLOWCTL  │ 0x03           │ Credit  based  flow │ LE     │
                 │                    │                │ control mode        │        │
                 ├────────────────────┼────────────────┼─────────────────────┼────────┤
                 │BT_MODE_EXT_FLOWCTL │ 0x04           │ Extended     Credit │ Any    │
                 │                    │                │ based  flow control │        │
                 │                    │                │ mode                │        │
                 └────────────────────┴────────────────┴─────────────────────┴────────┘

RESOURCES

        <http://www.bluez.org>

REPORTING BUGS

        <linux-bluetooth@vger.kernel.org>

SEE ALSO

       socket(7), l2test(1)

       Free use of this software is granted under ther terms of the  GNU  Lesser  General  Public
       Licenses (LGPL).