sco

package: libbluez-devel

title: sco(7)

summary: SCO transport

text:
# sco(7)

## NAME
sco - SCO transport

## SYNOPSIS

```
#include <sys/socket.h>
#include <bluetooth/bluetooth.h>
#include <bluetooth/sco.h>
sco_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_SCO);
```

## DESCRIPTION
The SCO logical transport, is a symmetric, point-to-point transport between the Central and a specific Peripheral. The SCO logical transport reserves slots and can therefore be considered as a circuit-switched connection between the Central and the Peripheral.

In addition to the reserved slots, when eSCO is supported, a retransmission window follows immediately after. Together, the reserved slots and the retransmission window form the complete eSCO window.

## SOCKET ADDRESS

```
struct sockaddr_sco {

    sa_family_t     sco_family;

    bdaddr_t        sco_bdaddr;
};
```

Example:

```
struct sockaddr_sco addr;
memset(&addr, 0, sizeof(addr));
addr.sco_family = AF_BLUETOOTH;
bacpy(&addr.sco_bdaddr, bdaddr);
```

## SOCKET OPTIONS (SOL_BLUETOOTH)
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 - 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(sco_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(sco_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,

                     &defer_setup, sizeof(defer_setup));
if (err == -1) {

    perror("setsockopt");

    return err;
}
err = listen(sco_socket, 5);
if (err) {

    perror("listen");

    return err;
}
struct sockaddr_sco remote_addr = {0};
socklen_t addr_len = sizeof(remote_addr);
int new_socket = accept(sco_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_VOICE (since Linux 3.11)
Transport voice settings, possible values:

```
struct bt_voice {

    uint16_t setting;
};
```

Define

Value

Description

BT_VOICE_TRANSPARENT

0x0003

Transparent output

BT_VOICE_CVSD_16BIT

0x0060

C-VSD output PCM 16-bit input

BT_VOICE_TRANSPARENT_16BIT

0x0063

Transparent output PCM 16-bit input

Example:

```
struct bt_voice voice;
memset(&voice, 0, sizeof(voice));
voice.setting = BT_VOICE_TRANSPARENT;
int err = setsockopt(sco_socket, SOL_BLUETOOTH, BT_VOICE, &voice,

                     sizeof(voice));
if (err == -1) {

    perror("setsockopt");

    return 1;
}
```

### BT_PKT_STATUS (since Linux 5.9)
Enable reporting packet status via BT_SCM_PKT_STATUS CMSG on received packets. Possible values:

Value

Description

0

Disable (default)

1

Enable

BT_SCM_PKT_STATUS

Level SOL_BLUETOOTH CMSG with data:

```
uint8_t pkt_status;
```

The values are equal to the "Packet_Status_Flag" defined in Core Specification v6.0 Sec. 5.4.3 pp. 1877:

pkt_status

Description

0x0

Correctly received data

0x1

Possibly invalid data

0x2

No data received

0x3

Data partially lost

### BT_PHY (since Linux 5.10)
Transport supported PHY(s), read-only (no setsockopt support). 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_2M_1SLOT

BIT 3

EDR 2Mbps 1SLOT

BT_PHY_BR_2M_3SLOT

BIT 4

EDR 2Mbps 3SLOT

BT_PHY_BR_3M_1SLOT

BIT 6

EDR 3Mbps 1SLOT

BT_PHY_BR_3M_3SLOT

BIT 7

EDR 3Mbps 3SLOT

### BT_CODEC (since Linux 5.14)
Transport codec offload, possible values:

```
struct bt_codec {

    uint8_t id;

    uint16_t cid;

    uint16_t vid;

    uint8_t data_path_id;

    uint8_t num_caps;

    struct codec_caps {

        uint8_t len;

        uint8_t data[];

    } caps[];
} __attribute__((packed));
struct bt_codecs {

    uint8_t num_codecs;

    struct bt_codec codecs[];
} __attribute__((packed));
```

Example:

```
char buffer[sizeof(struct bt_codecs) + sizeof(struct bt_codec)];
struct bt_codec *codecs = (void *)buffer;
memset(codecs, 0, sizeof(codecs));
codec->num_codecs = 1;
codecs->codecs[0].id = 0x05;
codecs->codecs[0].data_path_id = 1;
int err = setsockopt(sco_socket, SOL_BLUETOOTH, BT_CODEC, codecs,

                     sizeof(buffer));
if (err == -1) {

    perror("setsockopt");

    return 1;
}
```

## SOCKET OPTIONS (SOL_SOCKET)
SOL_SOCKET level socket options that modify generic socket features (SO_SNDBUF, SO_RCVBUF, etc.) have their usual meaning, see socket(7).

The SOL_SOCKET level SCO socket options that have Bluetooth-specific handling in kernel are listed below.

### SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
See https://docs.kernel.org/networking/timestamping.html

For SCO sockets, software RX timestamps are supported. Software TX timestamps (SOF_TIMESTAMPING_TX_SOFTWARE) 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. Completion timestamps are only supported on controllers that have SCO flow control. 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_OPT_ID;
setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
```

Example (Read TX timestamps):

```
union {

    char buf[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
The following ioctls with operation specific for SCO sockets are available.

### SIOCETHTOOL (since Linux 6.16-rc1)
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 <linux/ethtool.h>
#include <linux/sockios.h>
#include <net/if.h>
#include <sys/socket.h>
#include <sys/ioctl.h>
...
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_SCO);
if (sk < 0)

    goto error;
if (ioctl(sk, SIOCETHTOOL, &ifr))

    goto error;
sof_available = cmd.so_timestamping;
```

## RESOURCES
http://www.bluez.org

## REPORTING BUGS
linux-bluetooth@vger.kernel.org

## SEE ALSO
socket(7), scotest(1)

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


bobcat

title: bobcat(7)

text:
# bobcat(7)

## NAME
Bobcat - Overview of classes in the Bobcat library

## DESCRIPTION
The classes of the Bobcat library may be used after including bobcat/classname in sources.

Generally, programs using the Bobcat library must be at least linked against the Bobcat library. Refer to section LINKING for more informatin about linking programs to required libraries.

All classes and other elements are defined in the FBB namespace. For some classes manipulators are available, which are defined in the FBB namespace. An overview of all manipulators defined in the FBB namespace is provided by man -e bobcat manipulators.

Beyond this section the section CATEGORIES groups classes that somehow belong together in various categories.

The following classes and functions are available:

FBB::Align: Specifies Table(Buf) column and element alignments.

(Manpage: man -e bobcat align)

FBB::Arg: Interfaces the command line arguments, allowing for short- and long options. The class is implemented as a Singleton.

(Manpage: man -e bobcat arg)

FBB::ArgConfig: Inherits from Arg and ConfigFile allowing for options to be specified as command line options and/or configuration file options. The class is implemented as a Singleton.

(Manpage: man -e bobcat argconfig)

FBB::A2x: Ascii-to-x conversions of any type supporting extractions from i[string]stream objects. (Manpage: man -e bobcat a2x)

FBB::BigInt: Wrapper class around the openssl BN_ functions for unlimited integer precision arithmetic.

(Manpage: man -e bobcat bigint)

FBB::binary_search: A modification of the STL binary_search algorithm returning the location of the searched value in a sorted series of values.

(Manpage: man -e bobcat binarysearch)

FBB::BinOps: A series of function templates implementing binary operators for classes that implement the matching binary assignment operators themselves.

(Manpage: man -e bobcat binops)

FBB::BinOpsBase: A class template implementing binary operators and compound assignment operators for classes that themselves implement swap members and members implementing the basic binary operation on objects of their class types themselves.

(Manpage: man -e bobcat binopsbase)

FBB::CerrExtractor: Executes child processes not expecting input but maybe writing its standard error stream.

(Manpage: man -e bobcat cerrextractor)

FBB::CGI: a class implementing the facilities accessing the data made available through the Common Gateway Interface.

(Manpage: man -e bobcat cgi)

FBB::Cidr: a class testing whether IP4 Internet addresses belong to address ranges defined by Classless Inter-Domain Routing (CIDR) address block specifications.

(Manpage: man -e bobcat cidr)

FBB::CinInserter: Executes child processes expecting input but not producing standard output.

(Manpage: man -e bobcat cininserter)

FBB::ClientSocket: a socket for tcp-communication with a server.

(Manpage: man -e bobcat clientsocket)

FBB::CmdFinder: Command-function associations.

(Manpage: man -e bobcat cmdfinder)

FBB::CmdFinderBase: Base class for CmdFinder.

(Manpage: man -e bobcat cmdfinderbase)

FBB::Config: Processing standard configuration files.

(Manpage: man -e bobcat config)

FBB::ConfigFile: Processing standard configuration files (deprecated, use Config).

(Manpage: man -e bobcat configfile)

FBB::CoutExtractor: Executes child processes not expecting input but maybe producing standard output.

(Manpage: man -e bobcat coutextractor)

FBB::CryptBuf: Base class for DecryptBuf and EncryptBuf.

(Manpage: man -e bobcat cryptbuf)

FBB::CSVTable: Construct tables row-by-row.

(Manpage: man -e bobcat csvtable)

FBB::CSV4180: Objects of this class allow for easy handling of comma-separated values (implements RFC 4180).

(Manpage: man -e bobcat csv4180)

FBB::DateTime: Manipulations with date and time values.

(Manpage: man -e bobcat datetime)

FBB::DecryptBuf: Decrypting information.

(Manpage: man -e bobcat decryptbuf)

FBB::DiffieHellman: Computing shared keys using the Diffie-Hellman algorithm.

(Manpage: man -e bobcat diffiehellman)

FBB::DigestBuf: Computing message digests.

(Manpage: man -e bobcat digestbuf)

FBB::EncryptBuf: Encrypting information.

(Manpage: man -e bobcat encryptbuf)

FBB::Eoi: std::streambuf offering the eoi manipulator.

(Manpage: man -e bobcat eoi)

FBB::Eoi: std::streambuf offering the eoi manipulator.

(Manpage: man -e bobcat eoi)

FBB::EoiBuf: std::streambuf offering the eoi manipulator and a configurable stream buffer.

(Manpage: man -e bobcat eoibuf)

FBB::Exception: objects of this class accept ostream insertions, and are also std::exception objects.

(Manpage: man -e bobcat exception)

FBB::Exec: Executes child processes not expecting input and not producing standard output.

(Manpage: man -e bobcat exec)

FBB::Field: class template retrieving and modifying position based fields in numbers using configurable number systems.

(Manpage: man -e bobcat field)

FBB::Fork: Defines fork(2) as part of a Template Algorithm Design Pattern.

(Manpage: man -e bobcat fork)

FBB::GetHostent: Obtains hostent struct from hostname or -address.

(Manpage: man -e bobcat gethostent)

FBB::Glob: Obtain a list of files matching a certain pattern.

(Manpage: man -e bobcat glob)

FBB::HmacBuf: Computing HMAC message digests.

(Manpage: man -e bobcat hmacbuf)

FBB::Hostname: Derived from Hostent, allows the initialization from a std::string, or from an FBB::InetAddrress.

(Manpage: man -e bobcat hostname)

FBB::IBase64Stream: stream implementing base64 encoding and decoding, using a FBB::Base64Streambuf stream buffer.

(Manpage: man -e bobcat ibase64stream)

FBB::IBase64Buf: FBB::IFilterBuf specialization implementing base64 encoding and decoding.

(Manpage: man -e bobcat ibase64buf)

FBB::IFdStream: stream extracting information from a device whose file descriptor is available.

(Manpage: man -e bobcat ifdstream)

FBB::IFdBuf: Input stream buffer initialized by a file descriptor.

(Manpage: man -e bobcat ifdbuf)

FBB::IFilterBuf: std::streambuf specialization implementing an std::istream filtering design pattern.

(Manpage: man -e bobcat ifilterbuf)

FBB::Indent: Class and manipulators performing text indentation.

(Manpage: man -e bobcat indent)

FBB::InetAddress: Base class (no public constructor) for objects representing an internet address as used with sockets. Contains address and portnumbers.

(Manpage: man -e bobcat inetaddress)

FBB::IOStream: class combining std::istream and std::ostream features.

(Manpage: man -e bobcat iostream)

FBB::IOBuf: std::streambuf specialization allowing combined input and output operations.

(Manpage: man -e bobcat iobuf)

FBB::ISharedStream: std::istream operations on shared memory.

(Manpage: man -e bobcat isharedstream)

FBB::IQuotedPrintableStream: stream implementing quoted printable encoding and decoding, using a FBB::IQuotedPrintableBuf stream buffer.

(Manpage: man -e bobcat iquotedprintablestream)

FBB::IQuotedPrintableBuf: FBB::IFilterBuf specialization implementing quoted printable encoding and decoding.

(Manpage: man -e bobcat iquotedprintablebuf)

FBB::IRandStream: stream to extract random numbers from.

(Manpage: man -e bobcat irandstream)

FBB::ISymCryptStream: stream implementing symmetric encryption and decryption, using a FBB::ISymCryptStreambuf stream buffer.

(Manpage: man -e bobcat isymcryptstream)

FBB::ISymCryptStreambuf: FBB::IFilterBuf specialization implementing symmetric cryptography.

(Manpage: man -e bobcat isymcryptstreambuf)

FBB::Iterator: a class template creating a bidirectional iterator returning values of a specified type.

(Manpage: man -e bobcat iterator)

FBB::Hash...: Various class templates implementing mapping containers using hashing.

(Manpage: man -e bobcat hash)

FBB::Hostent: Wrapper around the hostent struct.

(Manpage: man -e bobcat hostent)

FBB::LDC: Large Digital Converter converts (large) values for various radices.

(Manpage: man -e bobcat ldc)

FBB::level: Manipulator setting the log-level of FBB::Log objects.

(Manpage: man -e bobcat level)

FBB::LinearMap: a class template container implementing a map using a linear search algorithm.

(Manpage: man -e bobcat linearmap)

FBB::lm: Manipulator setting the left margin of FBB::OFoldStream objects.

(Manpage: man -e bobcat lm)

FBB::LocalClientSocket: a Unix domain socket for tcp-communication with a Unix domain (local) server.

(Manpage: man -e bobcat localclientsocket)

FBB::LocalServerSocket: defines a Unix domain socket to which clients on the local host can connect.

(Manpage: man -e bobcat localserversocket)

FBB::LocalSocketBase: Base class for LocalClientSocket and LocalServerSocket.

(Manpage: man -e bobcat localsocketbase)

FBB::Log: std::ostream handling log messages.

(Manpage: man -e bobcat log)

FBB::LogBuf: std::streambuf handling log messages.

(Manpage: man -e bobcat logbuf)

FBB::MailHeaders: extracts mail headers from SMTP-email.

(Manpage: man -e bobcat mailheaders)

FBB::Manipulators: manipulators defined in the namespace FBB.

(Manpage: man -e bobcat manipulators)

FBB::Mbuf: std::streambuf specialization for inserting messages, mainly used by FBB::Mstream objects.

(Manpage: man -e bobcat mbuf)

FBB::Milter: interfaces the sendmail mail filter facilities.

(Manpage: man -e bobcat milter)

FBB::mlm: Manipulator modifying the left margin of FBB::OFoldStream objects.

(Manpage: man -e bobcat mlm)

FBB::Mstream: Inserts messages into streams.

(Manpage: man -e bobcat mstream)

FBB::MultiBuf: std::streambuf specializations performing insertions to multiple std::ostream objects.

(Manpage: man -e bobcat multibuf)

FBB::OMutexStream: Mutex protected std::ostream.

(Manpage: man -e bobcat mxstream)

FBB::OFdStream: stream inserting information into a device whose file descriptor is available.

(Manpage: man -e bobcat ofdstream)

FBB::OFdBuf: Output stream buffer initialized by a file descriptor.

(Manpage: man -e bobcat ofdbuf)

FBB::OFilterBuf: std::streambuf specialization implementing an std::ostream filtering design pattern.

(Manpage: man -e bobcat ofilterbuf)

FBB::OFoldStream: std::ostream using an OFoldBuf as its streambuf.

(Manpage: man -e bobcat ofoldstream)

FBB::OFoldBuf: OFilterBuf (std::streambuf) specialization folding text lines between left and right margins.

(Manpage: man -e bobcat ofoldbuf)

FBB::OHexBuf: OHexBuf (std::streambuf) specialization inserting characters into a stream by their hex values.

(Manpage: man -e bobcat ohexbuf)

FBB::OneKey: Single keystroke input, not requiring `Return’.

(Manpage: man -e bobcat onekey)

FBB::OSharedStream: std::ostream operations on shared memory.

(Manpage: man -e bobcat osharedstream)

FBB::Pattern: Regular expression pattern matching.

(Manpage: man -e bobcat pattern)

FBB::Pipe: Defines a system level pipe.

(Manpage: man -e bobcat pipe)

FBB::PrimeFactors: Prime-number factorization of (BigInt) values.

(Manpage: man -e bobcat primefactors)

FBB::Process: Runs child processes, defining pipes between parents and child processes.

(Manpage: man -e bobcat process)

FBB::PtrIter: Input iterator whose dereferenced value returns a pointer rather than a reference to an element. Also offers: a ptrIter function template.

(Manpage: man -e bobcat ptriter)

FBB::RandBuf: implements a streambuf generating random numbers.

(Manpage: man -e bobcat randbuf)

FBB::Ranger: a class template creating ranges that are accepted by range-based for-loops. Also offered: a ranger function template.

(Manpage: man -e bobcat ranger)

FBB::ReadLineBuf: implements a streambuf using the Gnu readline library to allow editing an std::istream’s content.

(Manpage: man -e bobcat readlinebuf)

FBB::ReadLineHistory: provides access to the history of lines read from a ReadLineBuf.

(Manpage: man -e bobcat readlinehistory)

FBB::ReadLineStream: std::istream class using a ReadLineBuf for its std::streambuf.

(Manpage: man -e bobcat readlinestream)

FBB::Redirector: Defines system level file redirection.

(Manpage: man -e bobcat redirector)

FBB::repeat: Two short extensions of the STL for_each generic algorithm.

(Manpage: man -e bobcat repeat)

FBB::Reverse: a class template creating a reverse iterator returning values of a specified type.

(Manpage: man -e bobcat reverse)

FBB::Selector: Offers timed delays and multiple file I/O.

(Manpage: man -e bobcat selector)

FBB::Semaphore: Dijkstra’s (1962) Semaphore data type.

(Manpage: man -e bobcat semaphore)

FBB::ServerSocket: defines a socket to which clients can connect.

(Manpage: man -e bobcat serversocket)

FBB::SharedBlock: Shared memory data block info.

(Manpage: man -e bobcat sharedblock)

FBB::SharedCondition: Shared memory condition variable.

(Manpage: man -e bobcat sharedcondition)

FBB::SharedMemory: Shared memory structure.

(Manpage: man -e bobcat sharedmemory)

FBB::SharedMutex: Mutex for shared memory.

(Manpage: man -e bobcat sharedmutex)

FBB::SharedPos: Shared Memory offset controller.

(Manpage: man -e bobcat sharedpos)

FBB::SharedReadme: Background info about the implementation of Bobcat’s Shared Memory.

(Manpage: man -e bobcat sharedreadme)

FBB::SharedSegment: Shared memory data structure.

(Manpage: man -e bobcat sharedsegment)

FBB::SharedStream: I/O operations on shared memory.

(Manpage: man -e bobcat sharedstream)

FBB::SharedBuf: std::streambuf interfacing to shared memory.

(Manpage: man -e bobcat sharedbuf)

FBB::Signal: Defines signals, allowing signal handlers to use object’s data members c.q. to call object’s members functions.

(Manpage: man -e bobcat signal)

FBB::SocketBase: Base class for ClientSocket and ServerSocket.

(Manpage: man -e bobcat socketbase)

FBB::Stat: Determines file characteristics.

(Manpage: man -e bobcat stat)

FBB::StdExtractor: Executes child processes not expecting input but maybe writing their standard output and error streams.

(Manpage: man -e bobcat stdextractor)

FBB::String: Offers extended std::string functionality.

(Manpage: man -e bobcat string)

FBB::StringLine: Offers operator>> extracting lines from std::istream objects.

(Manpage: man -e bobcat stringline)

FBB::SyslogBuf: streambuf to Buffer generating syslog(3) messages.

(Manpage: man -e bobcat syslogbuf)

FBB::SyslogStream: stream to Output stream inserting syslog(3) messages.

(Manpage: man -e bobcat syslogstream)

FBB::fswap: templates implementing memory bytes based swap functionality

(Manpage: man -e bobcat fswap)

FBB::Table: Display tables row- or column-wise.

(Manpage: man -e bobcat table)

FBB::TableBuf: Display tables row- or column-wise.

(Manpage: man -e bobcat tablebuf)

FBB::TableLines: Support class for the class Table(Buf).

(Manpage: man -e bobcat tablelines)

FBB::TableSupport: Support class for the class Table(Buf).

(Manpage: man -e bobcat tablesupport)

FBB::TempStream: Temporary fstream.

(Manpage: man -e bobcat tempstream)

FBB::Tty: Controls echoing of characters entered at the terminal.

(Manpage: man -e bobcat tty)

FBB::TypeTrait: Traits class template to determine various characteristics of types.

(Manpage: man -e bobcat typetrait)

FBB::User: Determines the current user’s parameters from /etc/passwd.

(Manpage: man -e bobcat user)

FBB::Xpointer: sets and retrieves the X-windows pointer.

(Manpage: man -e bobcat xpointer)

FBB::X2a: x-to-Ascii conversions of any type supporting insertions into o[string]stream objects.

(Manpage: man -e bobcat x2a)

## CATEGORIES
This section groups classes that somehow belong together. The following categories are offered:

o

COMMAND LINE INTERFACE AND CONFIGURATION FILES

o

CONVERSIONS

o

DATE AND TIME

o

ERRORS AND MESSAGE HANDLING

o

GENERIC ALGORITHM EXTENSIONS

o

INTERNET / NETWORKING

o

OPENSSL AND ENCRYPTION

o

PATTERN MATCHING

o

PROCESSES, SIGNALS, THREADS

o

STREAMS AND FILES

o

SHARED MEMORY

o

TABLES

o

VARIOUS TEMPLATES

o

VARIOUS OTHER CLASSES

o

COMMAND LINE INTERFACE AND CONFIGURATION FILES

FBB::Arg: Interfaces the command line arguments, allowing for short- and long options. The class is implemented as a Singleton.

(Manpage: man -e bobcat arg)

FBB::ArgConfig: Inherits from Arg and ConfigFile allowing for options to be specified as command line options and/or configuration file options. The class is implemented as a Singleton.

(Manpage: man -e bobcat argconfig)

FBB::CmdFinder: Command-function associations.

(Manpage: man -e bobcat cmdfinder)

FBB::CmdFinderBase: Base class for CmdFinder.

(Manpage: man -e bobcat cmdfinderbase)

FBB::Config: Processing standard configuration files.

(Manpage: man -e bobcat configfile)

FBB::ConfigFile: Processing standard configuration files (deprecated, use Config).

(Manpage: man -e bobcat configfile)

o

CONVERSIONS

FBB::A2x: Ascii-to-x conversions of any type supporting extractions from i[string]stream objects. (Manpage: man -e bobcat a2x)

FBB::BigInt: Wrapper class around the openssl BN_ functions for unlimited integer precision arithmetic.

(Manpage: man -e bobcat bigint)

FBB::CSV4180: Objects of this class allow easy handling of comma-separated values (implements RFC 4180).

(Manpage: man -e bobcat csv)

FBB::IBase64Stream: stream implementing base64 encoding and decoding, using a FBB::Base64Streambuf stream buffer.

(Manpage: man -e bobcat ibase64stream)

FBB::IBase64Buf: FBB::IFilterBuf specialization implementing base64 encoding and decoding.

(Manpage: man -e bobcat ibase64buf)

FBB::IQuotedPrintableStream: stream implementing quoted printable encoding and decoding, using a FBB::IQuotedPrintableBuf stream buffer.

(Manpage: man -e bobcat iquotedprintablestream)

FBB::IQuotedPrintableBuf: FBB::IFilterBuf specialization implementing quoted printable encoding and decoding.

(Manpage: man -e bobcat iquotedprintablebuf)

FBB::LDC: Large Digital Converter converts (large) values for various radices.

(Manpage: man -e bobcat ldc)

FBB::X2a: x-to-Ascii conversions of any type supporting insertions into o[string]stream objects.

(Manpage: man -e bobcat x2a)

o

DATE AND TIME

FBB::DateTime: Manipulations with date and time values.

(Manpage: man -e bobcat datetime)

o

ERRORS AND MESSAGE HANDLING

FBB::Exception: objects of this class accept ostream insertions, and are also std::exception objects.

(Manpage: man -e bobcat exception)

FBB::level: Manipulator setting the log-level of FBB::Log objects.

(Manpage: man -e bobcat level)

FBB::Log: std::ostream handling log messages.

(Manpage: man -e bobcat log)

FBB::LogBuf: std::streambuf handling log messages.

(Manpage: man -e bobcat logbuf)

FBB::SyslogBuf: streambuf to Buffer generating syslog(3) messages.

(Manpage: man -e bobcat syslogbuf)

FBB::SyslogStream: stream to Output stream inserting syslog(3) messages.

(Manpage: man -e bobcat syslogstream)

o

GENERIC ALGORITHM EXTENSIONS

FBB::binary_search: A modification of the STL binary_search algorithm returning the location of the searched value in a sorted series of values.

(Manpage: man -e bobcat binarysearch)

FBB::LinearMap: a class template container implementing a map using a linear search algorithm.

(Manpage: man -e bobcat linearmap)

FBB::repeat: Two short extensions of the STL for_each generic algorithm.

(Manpage: man -e bobcat repeat)

o

INTERNET / NETWORKING

FBB::CGI: a class implementing the facilities accessing the data made available through the Common Gateway Interface.

(Manpage: man -e bobcat cgi)

FBB::Cidr: a class testing whether IP4 Internet addresses belong to address ranges defined by Classless Inter-Domain Routing (CIDR) address block specifications.

(Manpage: man -e bobcat cidr)

FBB::ClientSocket: a socket for tcp-communication with a server.

(Manpage: man -e bobcat clientsocket)

FBB::GetHostent: Obtains hostent struct from hostname or -address.

(Manpage: man -e bobcat gethostent)

FBB::Hostname: Derived from Hostent, allows the initialization from a std::string, or from an FBB::InetAddrress.

(Manpage: man -e bobcat hostname)

FBB::InetAddress: Base class (no public constructor) for objects representing an internet address as used with sockets. Contains address and portnumbers.

(Manpage: man -e bobcat inetaddress)

FBB::Hostent: Wrapper around the hostent struct.

(Manpage: man -e bobcat hostent)

FBB::LocalClientSocket: a Unix domain socket for tcp-communication with a Unix domain (local) server.

(Manpage: man -e bobcat localclientsocket)

FBB::LocalServerSocket: defines a Unix domain socket to which clients on the local host can connect.

(Manpage: man -e bobcat localserversocket)

FBB::LocalSocketBase: Base class for LocalClientSocket and LocalServerSocket.

(Manpage: man -e bobcat localsocketbase)

FBB::MailHeaders: extracts mail headers from SMTP-email.

(Manpage: man -e bobcat mailheaders)

FBB::Milter: interfaces the sendmail mail filter facilities.

(Manpage: man -e bobcat milter)

FBB::ServerSocket: defines a socket to which clients can connect.

(Manpage: man -e bobcat serversocket)

FBB::SocketBase: Base class for ClientSocket and ServerSocket.

(Manpage: man -e bobcat socketbase)

o

OPENSSL AND ENCRYPTION

FBB::BigInt: Wrapper class around the openssl BN_ functions for unlimited integer precision arithmetic.

(Manpage: man -e bobcat bigint)

FBB::CryptBuf: Base class for DecryptBuf and EncryptBuf.

(Manpage: man -e bobcat cryptbuf)

FBB::DecryptBuf: Decrypting information.

(Manpage: man -e bobcat decryptbuf)

FBB::DiffieHellman: Computing shared keys using the Diffie-Hellman algorithm.

(Manpage: man -e bobcat diffiehellman)

FBB::DigestBuf: Computing message digests.

(Manpage: man -e bobcat digestbuf)

FBB::EncryptBuf: Encrypting information.

(Manpage: man -e bobcat encryptbuf)

FBB::HmacBuf: Computing HMAC message digests.

(Manpage: man -e bobcat hmacbuf)

FBB::ISymCryptStream: stream implementing symmetric encryption and decryption, using a FBB::ISymCryptStreambuf stream buffer.

(Manpage: man -e bobcat isymcryptstream)

FBB::ISymCryptStreambuf: FBB::IFilterBuf specialization implementing symmetric cryptography.

(Manpage: man -e bobcat isymcryptstreambuf)

o

PATTERN MATCHING

FBB::Glob: Obtain a list of files matching a certain pattern.

(Manpage: man -e bobcat glob)

FBB::Pattern: Regular expression pattern matching.

(Manpage: man -e bobcat pattern)

o

PROCESSES, SIGNALS, THREADS

FBB::Exec: Executes child processes not expecting input and not producing standard output.

(Manpage: man -e bobcat exec)

FBB::CerrExtractor: Executes child processes not expecting input but maybe writing its standard error stream.

(Manpage: man -e bobcat cerrextractor)

FBB::CoutExtractor: Executes child processes not expecting input but maybe producing standard output.

(Manpage: man -e bobcat coutextractor)

FBB::Fork: Defines fork(2) as part of a Template Algorithm Design Pattern.

(Manpage: man -e bobcat fork)

FBB::CinInserter: Executes child processes expecting input but not producing standard output.

(Manpage: man -e bobcat cininserter)

FBB::Process: Runs child processes, defining pipes between parents and child processes.

(Manpage: man -e bobcat process)

FBB::Semaphore: Dijkstra’s (1962) Semaphore data type.

(Manpage: man -e bobcat semaphore)

FBB::Signal: Defines signals, allowing signal handlers to use object’s data members c.q. to call object’s members functions.

(Manpage: man -e bobcat signal)

FBB::StdExtractor: Executes child processes not expecting input but maybe writing their standard output and error streams.

(Manpage: man -e bobcat stdextractor)

o

STREAMS AND FILES

FBB::DigestBuf: Computing message digests.

(Manpage: man -e bobcat digestbuf)

FBB::Eoi: std::streambuf offering the eoi manipulator.

(Manpage: man -e bobcat eoi)

FBB::EoiBuf: std::streambuf offering the eoi manipulator and a configurable stream buffer.

(Manpage: man -e bobcat eoibuf)

FBB::IFdStream: stream extracting information from a device whose file descriptor is available.

(Manpage: man -e bobcat ifdstream)

FBB::IFdBuf: Input stream buffer initialized by a file descriptor.

(Manpage: man -e bobcat ifdbuf)

FBB::IFilterBuf: std::streambuf specialization implementing an std::istream filtering design pattern.

(Manpage: man -e bobcat ifilterbuf)

FBB::IOStream: class combining std::istream and std::ostream features.

(Manpage: man -e bobcat iostream)

FBB::IOBuf: std::streambuf specialization allowing combined input and output operations.

(Manpage: man -e bobcat iobuf)

FBB::IRandStream: stream to extract random numbers from.

((Manpage: man -e bobcat irandstream))

FBB::ISharedStream: std::istream operations on shared memory.

(Manpage: man -e bobcat isharedstream)

FBB::lm: Manipulator setting the left margin of FBB::OFoldStream objects.

(Manpage: man -e bobcat lm)

FBB::Mbuf: std::streambuf specialization for inserting messages, mainly used by FBB::Mstream objects.

(Manpage: man -e bobcat mbuf)

FBB::mlm: Manipulator modifying the left margin of FBB::OFoldStream objects.

(Manpage: man -e bobcat mlm)

FBB::Mstream: Inserts messages into streams.

(Manpage: man -e bobcat mstream)

FBB::MultiBuf: std::streambuf specializations performing insertions to multiple std::ostream objects.

(Manpage: man -e bobcat multibuf)

FBB::OMutexStream: Mutex protected std::ostream.

(Manpage: man -e bobcat mxstream)

FBB::OFdStream: stream inserting information into a device whose file descriptor is available.

(Manpage: man -e bobcat ofdstream)

FBB::OFdBuf: Output stream buffer initialized by a file descriptor.

(Manpage: man -e bobcat ofdbuf)

FBB::OFilterBuf: std::streambuf specialization implementing an std::ostream filtering design pattern.

(Manpage: man -e bobcat ofilterbuf)

FBB::OFoldStream: std::ostream using an OFoldBuf as its streambuf.

(Manpage: man -e bobcat ofoldstream)

FBB::OFoldBuf: OFilterBuf (std::streambuf) specialization folding text lines between left and right margins.

(Manpage: man -e bobcat ofoldbuf)

FBB::OHexBuf: OHexBuf (std::streambuf) specialization inserting characters into a stream by their hex values.

(Manpage: man -e bobcat ohexbuf)

FBB::OSharedStream: std::ostream operations on shared memory.

(Manpage: man -e bobcat osharedstream)

FBB::Pipe: Defines a system level pipe.

(Manpage: man -e bobcat pipe)

FBB::RandBuf: implements a streambuf generating random numbers.

(Manpage: man -e bobcat randbuf)

FBB::ReadLineBuf: implements a streambuf using the Gnu readline library to allow editing an std::istream’s content.

(Manpage: man -e bobcat readlinebuf)

FBB::ReadLineHistory: provides access to the history of lines read from a ReadLineBuf.

(Manpage: man -e bobcat readlinehistory)

FBB::ReadLineStream: std::istream class using a ReadLineBuf for its std::streambuf.

(Manpage: man -e bobcat readlinestream)

FBB::Redirector: Defines system level file redirection.

(Manpage: man -e bobcat redirector)

FBB::Selector: Offers timed delays and multiple file I/O.

(Manpage: man -e bobcat selector)

FBB::SharedStream: I/O operations on shared memory.

(Manpage: man -e bobcat sharedstream)

FBB::SharedBuf: std::streambuf interfacing to shared memory.

(Manpage: man -e bobcat sharedbuf)

FBB::Stat: Determines file characteristics.

(Manpage: man -e bobcat stat)

FBB::TempStream: Temporary fstream.

(Manpage: man -e bobcat tempstream)

o

SHARED MEMORY

FBB::ISharedStream: std::istream operations on shared memory.

(Manpage: man -e bobcat isharedstream)

FBB::OSharedStream: std::ostream operations on shared memory.

(Manpage: man -e bobcat osharedstream)

FBB::SharedBlock: Shared memory data block info.

(Manpage: man -e bobcat sharedblock)

FBB::SharedCondition: Shared memory condition variable.

(Manpage: man -e bobcat sharedcondition)

FBB::SharedMemory: Shared memory structure.

(Manpage: man -e bobcat sharedmemory)

FBB::SharedMutex: Mutex for shared memory.

(Manpage: man -e bobcat sharedmutex)

FBB::SharedPos: Shared Memory offset controller.

(Manpage: man -e bobcat sharedpos)

FBB::SharedReadme: Background info about the implementation of Bobcat’s Shared Memory.

(Manpage: man -e bobcat sharedreadme)

FBB::SharedSegment: Shared memory data structure.

(Manpage: man -e bobcat sharedsegment)

FBB::SharedStream: I/O operations on shared memory.

(Manpage: man -e bobcat sharedstream)

FBB::SharedBuf: std::streambuf interfacing to shared memory.

(Manpage: man -e bobcat sharedbuf)

o

TABLES

FBB::Align: Specifies Table(Buf) column and element alignments.

(Manpage: man -e bobcat align)

FBB::CSVTable: Construct tables row-by-row.

(Manpage: man -e bobcat csvtable)

FBB::Table: Display tables row- or column-wise.

(Manpage: man -e bobcat table)

FBB::TableBuf: Display tables row- or column-wise.

(Manpage: man -e bobcat tablebuf)

FBB::TableLines: Support class for the class Table(Buf).

(Manpage: man -e bobcat tablelines)

FBB::TableSupport: Support class for the class Table(Buf).

(Manpage: man -e bobcat tablesupport)

o

VARIOUS TEMPLATES

FBB::binary_search: A modification of the STL binary_search algorithm returning the location of the searched value in a sorted series of values.

(Manpage: man -e bobcat binarysearch)

FBB::BinOps: A series of function templates implementing binary operators for classes that implement the matching binary assignment operators themselves.

(Manpage: man -e bobcat binops)

FBB::BinOpsBase: A class template implementing binary operators and compound assignment operators for classes that themselves implement swap members and members implementing the basic binary operation on objects of their class types themselves.

(Manpage: man -e bobcat binopsbase)

FBB::Field: class template retrieving and modifying position based fields in numbers using configurable number systems.

(Manpage: man -e bobcat field)

FBB::fswap: templates implementing memory bytes based swap functionality

(Manpage: man -e bobcat fswap)

FBB::Hash...: Various class templates implementing mapping containers using hashing.

(Manpage: man -e bobcat hash)

FBB::Iterator: a class template creating a bidirectional iterator returning values of a specified type.

(Manpage: man -e bobcat iterator)

FBB::LinearMap: a class template container implementing a map using a linear search algorithm.

(Manpage: man -e bobcat linearmap)

FBB::PtrIter: Input iterator whose dereferenced value returns a pointer rather than a reference to an element. Also offers: a ptrIter function template.

(Manpage: man -e bobcat ptriter)

FBB::Ranger: a class template creating ranges that are accepted by range-based for-loops. Also offered: a ranger function template.

(Manpage: man -e bobcat ranger)

FBB::repeat: Two short extensions of the STL for_each generic algorithm.

(Manpage: man -e bobcat repeat)

FBB::Reverse: a class template creating a reverse iterator returning values of a specified type.

(Manpage: man -e bobcat reverse)

FBB::TypeTrait: Traits class template to determine various characteristics of types.

(Manpage: man -e bobcat typetrait)

o

VARIOUS OTHER CLASSES

FBB::CSV: Objects of this class allow easy handling of comma-separated values.

(Manpage: man -e bobcat csv)

FBB::Indent: Class and manipulators performing text indentation.

(Manpage: man -e bobcat indent)

FBB::Manipulators: manipulators defined in the namespace FBB.

(Manpage: man -e bobcat manipulators)

FBB::OneKey: Single keystroke input, not requiring `Return’.

(Manpage: man -e bobcat onekey)

FBB::PrimeFactors: Pprime-number factorization of (BigInt) values.

(Manpage: man -e bobcat primefactors)

FBB::String: Offers extended std::string functionality.

(Manpage: man -e bobcat string)

FBB::StringLine: Offers operator>> extracting lines from std::istream objects.

(Manpage: man -e bobcat stringline)

FBB::Tty: Controls echoing of characters entered at the terminal.

(Manpage: man -e bobcat tty)

FBB::User: Determines the current user’s parameters from /etc/passwd.

(Manpage: man -e bobcat user)

FBB::Xpointer: sets and retrieves the X-windows pointer.

(Manpage: man -e bobcat xpointer)

## LINKING
To link programs against the shared Bobcat library (e.g., libbobcat5.so) it is usually sufficient to merely specify -lbobcat. E.g.,

```
    g++ --std=c++2a main.cc -lbobcat

```

Note: libraries that are indirectly required are no longer automatically linked to your program. With some classes (e.g., BigInt) the libcrypto library must also be specified, and programs using such classes must be linked against bobcat and crypto:

```
    g++ --std=c++2a main.cc -lbobcat -lcrypto

```

Man-pages of classes requiring additional libraries mention these additional libraries in their SYNOPSIS sections. When using static linking, the situation is slightly more problematic, and no general rule can be provided here. To create a statically linked program the flag -static must be provided, but in addition the -pthread flag must often be specified as well. If, when statically linking your program, undefined references to pthread_... identifiers are reported, then that is a sure sign that you need to provide the -pthread flag as well.

When using static linking additional libraries, not specified at the man-pages, may also be required. E.g., when using the Xpointer class and using static linking, the command becomes:

```
    g++  main.cc -static -pthread -lbobcat -lX11 -lxcb  -lXdmcp -lXau

```

When encountering undefined references when using static linking missing libraries may be suggested by the linker or by its error messages. Alternatively, the missing libraries may be found by searching the Internet.

## FILES
o

/usr/include/bobcat/<classname>:

o

/usr/lib/libbobcat.*:

(shared, static libraries)

## SEE ALSO
The individual bobcat/3<class> header files, with man-pages accessible using man -e bobcat class (all lowercase names)

## BUGS
No Reported Bugs.

## BOBCAT PROJECT FILES
o

https://fbb-git.gitlab.io/bobcat/: gitlab project page;

o

bobcat_5.11.01-x.dsc: detached signature;

o

bobcat_5.11.01-x.tar.gz: source archive;

o

bobcat_5.11.01-x_i386.changes: change log;

o

libbobcat1_5.11.01-x_*.deb: debian package containing the libraries;

o

libbobcat1-dev_5.11.01-x_*.deb: debian package containing the libraries, headers and manual pages;

## BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

## COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).

## AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).


sharedreadme

title: sharedreadme(7bobcat)

summary: Description of Bobcat\(cqs shared memory classes

text:
# sharedreadme(7bobcat)

## NAME
SharedREADME - Description of Bobcat’s shared memory classes

## DESCRIPTION
The following shared memory classes are available:

o

SharedBlock(3bobcat)

The class SharedBlock(3bobcat) defines a small object consisting of a SharedMutex and a (shared segment) id. If offers functionality to set and retrieve the id, and to lock and unlock the SharedMutex. SharedBlock objects are used by SharedSegment(3bobcat) objects to keep track of which segments actually contain the shared memory data. It’s a bookkeeping helper class.

o

SharedSegment(3bobcat)

The class SharedSegment (cf. figure images/sharedsegment1.jpg) interfaces to actual shared memory. Its main member function is the static member create, returning a pointer to a newly allocated SharedMemory object.

The member create receives as its input parameters the number of blocks, the size of the segments allocated by SharedSegment, and the segment’s access mode (as used by, e.g., chmod(1)). It returns a pointer to the allocated SharedSegment, and its ID (set using a pointer to an int, passed as its first parameter).

Although the SharedSegment class defines an array of a single SharedBlock(3bobcat) object, in fact it will contain d_nBlocks SharedBlock objects. The member create first allocates a block of raw memory of the required total size. Next it initializes the first part of this raw, shared memory, using the SharedSegment constructor and placement new. Next, the remaining amount of raw shared memory is initialized with d_nBlocks - 1 SharedBlock objects, again using placement new (cf. figure images/sharedsegment2.jpg).

o

SharedPos(3bobcat)

The class SharedPos(3bobcat) monitors position information in the shared memory segments managed by SharedSegment objects. SharedPos only has a default constructor, but offers a reset member receiving at construction time a pointer to a SharedSegment object.

o

SharedMemory(3bobcat)

The class SharedMemory(3bobcat) offers the standard interface to shared memory, defining members like read, get, write and put. It interfaces to a SharedSegment object, and uses a SharedPos object to keep track of the SharedMemory’s offsets.

A SharedMemory object itself resides in a program’s working memory, and not in the computer’s shared memory area. At any time the SharedMemory object only loads at most one actual block of the shared memory block managed by SharedSegment. The current position in the shared memory managed by SharedSegment is monitored by the SharedMemory’s SharedBlock d_pos member.

Following read/write operations the offset is updated accordingly. There’s only one offset, which is used by [IO]?SharedStream objects when requesting or updating offsets. a SharedMemory object offers safeguards against inappropriate use. E.g., if no memory has been allocated yet it may thow exceptions. Also, offsets can never exceed the SharedMemory’s maximum possible offset.

o

SharedMutex(3bobcat)

The class SharedMutex implements a non-recursive mutex that can be stored in shared memory. It merely offers lock and unlock members. Within one thread lock should never be called repeatedly unless unlock is called first. The unlock member may safely repeatedly be called; once the mutex has been unlocked, repeated requests to unlock the mutex are simply ignored. When a SharedMutex is destroyed it calls unlock. Use SharedMemory’s install member to define a SharedMutex object in shared memory, and use ptr->~SharedMutex() (with SharedMutex *ptr pointing at the SharedMutex object) to destroy it again.

o

SharedCondition(3bobcat)

The class SharedCondition implements a condition variable and an associated mutex, both created in shared memory controlled by a SharedMemory object. It offers all the functionality of std::condition_variable. A SharedCondition object itself is defined in a thread’s working memory, but interfaces to a `Condition’ object containing a condition variable and a mutex which are installed in shared memory. The size of this `Condition’ object is returned by the static member SharedCondition::size. SharedCondition members ensure that the thread has access to the `Condition’ object, and that the shared memory’s offset has not changed when returning from the SharedCondition’s members.

o

SharedBuf(3bobcat)

The class SharedBuf implements a std::streambuf specialization interfacing to a SharedMemory object. In addition to a default constructor which is an empty stub the class offers constructors which immediately interface to a SharedMemory object, as well as a member to (re)associate a SharedBuf object with a SharedMemory object.

o

SharedStream, ISharedStream, OSharedStream(3bobcat)

These stream classes offer stream-facilities operating on shared memory maintained by a SharedMemory object. The SharedStream class uses the SharedMemory’s seek member for both seekp and seekg, and uses SharedMemory’s offset member for both tellp and tellg. All shared stream objects, including ISharedStream, offer a member to initialize a SharedCondition

An overview of currently defined shared memory segments is shown by the command ipcs -ma. To remove a defined shared memory segment the command ipcrm -m <id> can be used, where <id> is the shared memory segment’s ID.

## EXAMPLE
See the sharedstream(3bobcat) man page.

## FILES
Images referred to in this man-page are located in the source distribution in bobcat/documents/images, or they can be found in the standard location of documentation files in your distribution (e.g., they are located in /usr/share/doc/libbobcat5/images).

## SEE ALSO
bobcat(7), ipcs(1), ipcrm(1), isharedstream(3bobcat), osharedstream(3bobcat), sharedblock(3bobcat), sharedcondition(3bobcat), sharedmemory(3bobcat), sharedmutex(3bobcat), sharedpos(3bobcat), sharedsegment(3bobcat), sharedstream(3bobcat), sharedbuf(3bobcat)

## BUGS
None Reported.

## BOBCAT PROJECT FILES
o

https://fbb-git.gitlab.io/bobcat/: gitlab project page;

o

bobcat_5.11.01-x.dsc: detached signature;

o

bobcat_5.11.01-x.tar.gz: source archive;

o

bobcat_5.11.01-x_i386.changes: change log;

o

libbobcat1_5.11.01-x_*.deb: debian package containing the libraries;

o

libbobcat1-dev_5.11.01-x_*.deb: debian package containing the libraries, headers and manual pages;

## BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

## COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).

## AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).


libbsd

package: libbsd-devel

title: libbsd(7)

summary: utility functions from BSD systems

text:
# libbsd(7)

## NAME
libbsd — utility functions from BSD systems

## DESCRIPTION
The libbsd library provides a set of compatibility macros and functions commonly found on BSD-based systems. Its purpose is to make those available on non-BSD based systems to ease portability.

The library can be used in an overlay mode, which is the preferred way, so that the code is portable and requires no modification to the original BSD code. This can be done easily with the pkg-config(3) library named libbsd-overlay. Or by adding the system-specific include directory with the bsd/ suffix to the list of system include paths. With gcc this could be -isystem ${includedir}/bsd. In addition the LIBBSD_OVERLAY pre-processor variable needs to be defined. The includes in this case should be the usual system ones, such as <unistd.h>.

The other way to use the library is to use the namespaced headers, this is less portable as it makes using libbsd mandatory and it will not work on BSD-based systems, and requires modifying original BSD code. This can be done with the pkg-config(3) library named libbsd. The includes in this case should be namespaced with bsd/, such as <bsd/unistd.h>.

The package also provides a bsd-ctor static library that can be used to inject automatic constructors into a program so that the setproctitle_init(3) function gets invoked automatically at startup time. This can be done with the pkg-config(3) library named libbsd-ctor.

## HEADERS
The following are the headers provided by libbsd, that extend the standard system headers. They can work in normal or overlay modes, for the former they need to be prefixed with bsd/.

<bitstring.h>

<err.h>

<getopt.h>

<grp.h>

<inttypes.h>

<libutil.h>

<md5.h>

<netinet/ip_icmp.h>

<nlist.h>

<pwd.h>

<readpassphrase.h>

<stdio.h>

<stdlib.h>

<string.h>

<stringlist.h>

<sys/bitstring.h>

<sys/cdefs.h>

<sys/endian.h>

<sys/param.h>

<sys/poll.h>

<sys/queue.h>

<sys/time.h>

<sys/tree.h>

<timeconv.h>

<unistd.h>

<vis.h>

<wchar.h>

The following is a libbsd specific convenience header, that includes some of the extended headers. It only works in non-overlay mode.

<bsd/bsd.h>

## ALTERNATIVES
Some functions have different prototypes depending on the BSD where they originated from, and these various implementations provided are selectable at build-time.

This is the list of functions that provide multiple implementations:

strnvis(3)

strnunvis(3)

NetBSD added strnvis(3) and strnunvis(3) but unfortunately made it incompatible with the existing one in OpenBSD and Freedesktop's libbsd (the former having existed for over ten years). Despite this incompatibility being reported during development (see http://gnats.netbsd.org/44977) they still shipped it. Even more unfortunately FreeBSD and later MacOS picked up this incompatible implementation. Provide both implementations and default for now to the historical one to avoid breakage, but we will switch to the NetBSD one in a later release, which is internally consistent with the other vis(3) functions and is now more widespread. Define LIBBSD_NETBSD_VIS to switch to the NetBSD one now. Define LIBBSD_OPENBSD_VIS to keep using the OpenBSD one.

## DEPRECATED
Some functions have been deprecated, they will emit warnings at compile time and possibly while being linked at run-time. This might be due to the functions not being portable at all to other systems, making the package not buildable there; not portable in a correct or non-buggy way; or because there are better more portable replacements now.

This is the list of currently deprecated macros and functions:

fgetln(3)

Unportable, requires assistance from the stdio layer. An implementation has to choose between leaking buffers or being reentrant for a limited amount of streams (this implementation chose the latter with a limit of 32). Use getline(3) instead, which is available in many systems and required by IEEE Std 1003.1-2008 (“POSIX.1”).

fgetwln(3)

Unportable, requires assistance from the stdio layer. An implementation has to choose between leaking buffers or being reentrant for a limited amount of streams (this implementation chose the latter with a limit of 32). Use fgetwc(3) instead, which is available in many systems and required by ISO/IEC 9899:1999 (“ISO C99”) and IEEE Std 1003.1-2001 (“POSIX.1”).

funopen(3)

Unportable, requires assistance from the stdio layer or some hook framework. On GNU systems the fopencookie(3) function can be used. Otherwise the code needs to be prepared for neither of these functions being available.

## SUPERSEDED
Some functions have been superseded by implementations in other system libraries, and might disappear on the next SONAME bump, assuming those other implementation have widespread deployment, or the implementations are present in all major libc for example.

MD5Init(3)

MD5Update(3)

MD5Pad(3)

MD5Final(3)

MD5Transform(3)

MD5End(3)

MD5File(3)

MD5FileChunk(3)

MD5Data(3)

The set of MD5 digest functions are now proxies for the implementations provided by the libmd companion library, so it is advised to switch to use that directly instead.

explicit_bzero(3)

This function is provided by glibc 2.25.

reallocarray(3)

This function is provided by glibc 2.26.

## SEE ALSO
arc4random(3bsd), bitstring(3bsd), byteorder(3bsd), closefrom(3bsd), errc(3bsd), expand_number(3bsd), explicit_bzero(3bsd), fgetln(3bsd), fgetwln(3bsd), flopen(3bsd), fmtcheck(3bsd), fparseln(3bsd), fpurge(3bsd), funopen(3bsd), getbsize(3bsd), getpeereid(3bsd), getprogname(3bsd), heapsort(3bsd), humanize_number(3bsd), md5(3bsd), nlist(3bsd), pidfile(3bsd), pwcache(3bsd), queue(3bsd), radixsort(3bsd), readpassphrase(3bsd), reallocarray(3bsd), reallocf(3bsd), setmode(3bsd), setproctitle(3bsd), stringlist(3bsd), strlcpy(3bsd), strmode(3bsd), strnstr(3bsd), strtoi(3bsd), strtonum(3bsd), strtou(3bsd), timeradd(3bsd), timeval(3bsd), tree(3bsd), unvis(3bsd), vis(3bsd), wcslcpy(3bsd).

## HISTORY
The libbsd project started in the Debian GNU/kFreeBSD port as a way to ease porting code from FreeBSD to the GNU-based system. Pretty early on it was generalized and a project created on FreeDesktop.org for other distributions and projects to use.

It is now distributed as part of most non-BSD distributions.


package: libcap-ng-utils

title: libdrop_ambient(7)

text:
# libdrop_ambient(7)

## NAME
libdrop_ambient - force application started with ambient capabilities to drop them

## DESCRIPTION
This library can be used via LD_PRELOAD to force an application started with ambient capabilities to drop them. It leaves other capabilities intact. This can also be linked against and automatically does the right thing. You do not need to make any calls into the library because all the work is done in the constructor which runs before main() is called.

## SEE ALSO
capabilities(7)

## AUTHOR
Steve Grubb


comedi

package: libcomedi

title: comedi(7)

text:
# comedi(7)

## NAME
comedi - the Linux Control and Measurement Device Interface

## SYNOPSIS
\#include <comedi.h>

\#include <comedilib.h>

## DESCRIPTION
The comedi package is a collection of hardware drivers, and the comedilib package is a collection of library routines that can be used to communicate with a variety of data acquisition boards, including A/D converters, D/A converters, digital I/O and timers.

## OTHER DOCUMENTATION
Hardware and driver configuration, and device-specific information, can be found in the comedi source, in the file Documentation/comedi/drivers.txt, or in the comedilib source, in the file doc/drivers.txt.

Programming documentation for comedilib can be found in the Comedilib manual.

## SEE ALSO
comedi_config(8), comedi_calibrate(8)

## VERSION
0.7.x

## AUTHOR
David Schleef


czmq

package: libczmq-devel

title: czmq(7)

summary: Overview of The high\-level C binding for 0MQ

text:
# czmq(7)

## NAME
czmq - Overview of The high-level C binding for 0MQ

## SYNOPSIS
Project czmq aims to ... (short marketing pitch)

It delivers several programs with their respective man pages: zmakecert.1 and public classes in a shared library: zactor.3 zarmour.3 zcert.3 zcertstore.3 zchunk.3 zclock.3 zconfig.3 zdigest.3 zdir.3 zdir_patch.3 zfile.3 zframe.3 zhash.3 zhashx.3 ziflist.3 zlist.3 zlistx.3 zloop.3 zmsg.3 zpoller.3 zproc.3 zsock.3 zstr.3 ztimerset.3 ztrie.3 zuuid.3 zauth.3 zbeacon.3 zgossip.3 zmonitor.3 zproxy.3 zrex.3 zsys.3

Generally you can compile and link against it like this:

```
#include <czmq.h>
cc ['flags'] 'files' -lczmq ['libraries']
```

## DESCRIPTION
This is a skeleton document created by zproject, which will not be regenerated automatically (by Makefiles nor project.xml re-parsing). You should add hand-written text here to detail whatever applies to Linux standard manpage Section 7 (note that other OSes may follow a different standard with similar concepts, and extend the recipes to package this document into a different section number):

```
7 Overview, conventions, and miscellaneous :

    Overviews or descriptions of various topics, conventions

    and protocols, character set standards, the standard

    filesystem layout, and miscellaneous other things.
```

### Classes
Something for developers to consider. Note there are separate man pages generated for public classes during build with contents taken from source code comments.

## AUTHORS
The czmq manual was written by the authors in the AUTHORS file.

## RESOURCES
Main web site:

Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>

## COPYRIGHT
Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

## NOTES
1.

zeromq-dev@lists.zeromq.org

mailto:zeromq-dev@lists.zeromq.org


debuginfod-client-config

package: libdebuginfod

title: debuginfod-client-config(7)

text:
# debuginfod-client-config(7)

## NAME
debuginfod-client-config - debuginfod client environment variables, cache control files and etc.

## SYNOPSIS
Several environment variables and control files control the behaviour of debuginfod client applications.

## ENVIRONMENT VARIABLES
$TMPDIR

This environment variable points to a file system to be used for temporary files. The default is /tmp.

$DEBUGINFOD_URLS

This environment variable contains a list of URL prefixes for trusted debuginfod instances. Alternate URL prefixes are separated by space. This environment variable may be set by /etc/profile.d scripts reading /etc/debuginfod/*.urls files.

$DEBUGINFOD_CACHE_PATH

This environment variable governs the location of the cache where downloaded files and cache-control files are kept. The default directory is chosen based on other environment variables, see below.

$DEBUGINFOD_PROGRESS

This environment variable governs the default progress function. If set, and if a progressfn is not explicitly set, then the library will configure a default progressfn. This function will append a simple progress message periodically to stderr. The default is no progress function output.

$DEBUGINFOD_VERBOSE

This environment variable governs the default file descriptor for verbose output. If set, and if a verbose fd is not explicitly set, then the verbose output will be produced on STDERR_FILENO.

$DEBUGINFOD_RETRY_LIMIT

This environment variable governs the default limit of retry attempts. If a query failed with errno other than ENOENT, will initiate several attempts within the limit.

$DEBUGINFOD_TIMEOUT

This environment variable governs the download commencing timeout for each debuginfod HTTP connection. A server that fails to provide at least 100K of data within this many seconds is skipped. The default is 90 seconds. (Zero or negative means "no timeout".)

$DEBUGINFOD_MAXTIME

This environment variable dictates how long the client will wait to complete the download a file found on a server in seconds. It is best used to ensure that a file is downloaded quickly or be rejected. The default is 0 (infinite time).

$DEBUGINFOD_MAXSIZE

This environment variable dictates the maximum size of a file to download in bytes. This is best used if the user would like to ensure only small files are downloaded. A value of 0 causes no consideration for size, and the client may attempt to download a file of any size. The default is 0 (infinite size).

$DEBUGINFOD_HEADERS_FILE

This environment variable points to a file that supplies headers to outbound HTTP requests, one per line. The header lines shouldn't end with CRLF, unless that's the system newline convention. Whitespace-only lines are skipped.

## CACHE
Before each query, the debuginfod client library checks for a need to clean the cache. If it's time to clean, the library traverses the cache directory and removes downloaded debuginfo-related artifacts and newly empty directories, if they have not been accessed recently.

Control files are located directly under the cache directory. They contain simple decimal numbers to set cache-related configuration parameters. If the files do not exist, the client library creates the files with the default parameter values as content.

After each query, the debuginfod client library deposits newly received files into a directory & file that is named based on the build-id. A failed query is also cached by a special file. The naming convention used for these artifacts is deliberately undocumented.

$XDG_CACHE_HOME/debuginfod_client/

Default cache directory, if $XDG_CACHE_HOME is set.

$HOME/.cache/debuginfod_client/

Default cache directory, if $XDG_CACHE_HOME is not set.

$HOME/.debuginfod_client_cache/

Deprecated cache directory, used only if preexisting.

cache_clean_interval_s

This control file gives the interval between cache cleaning rounds, in seconds. The default is 86400, one day. 0 means "immediately".

max_unused_age_s

This control file sets how long unaccessed debuginfo-related files are retained, in seconds. The default is 604800, one week. 0 means "immediately".

cache_miss_s

This control file sets how long to remember a query failure, in seconds. New queries for the same artifacts within this time window are short-circuited (returning an immediate failure instead of sending a new query to servers). This accelerates queries that probably would still fail. The default is 600, 10 minutes. 0 means "forget immediately".


drm

package: libdrm-devel

title: drm(7)

summary: Direct Rendering Manager

text:
# drm(7)

## NAME
drm - Direct Rendering Manager

## SYNOPSIS
\#include <xf86drm.h>

## DESCRIPTION
The Direct Rendering Manager (DRM) is a framework to manage Graphics Processing Units (GPUs). It is designed to support the needs of complex graphics devices, usually containing programmable pipelines well suited to 3D graphics acceleration. Furthermore, it is responsible for memory management, interrupt handling and DMA to provide a uniform interface to applications.

In earlier days, the kernel framework was solely used to provide raw hardware access to privileged user-space processes which implement all the hardware abstraction layers. But more and more tasks were moved into the kernel. All these interfaces are based on ioctl(2) commands on the DRM character device. The libdrm library provides wrappers for these system-calls and many helpers to simplify the API.

When a GPU is detected, the DRM system loads a driver for the detected hardware type. Each connected GPU is then presented to user-space via a character-device that is usually available as /dev/dri/card0 and can be accessed with open(2) and close(2). However, it still depends on the graphics driver which interfaces are available on these devices. If an interface is not available, the syscalls will fail with EINVAL.

### Authentication
All DRM devices provide authentication mechanisms. Only a DRM master is allowed to perform mode-setting or modify core state and only one user can be DRM master at a time. See drmSetMaster(3) for information on how to become DRM master and what the limitations are. Other DRM users can be authenticated to the DRM-Master via drmAuthMagic(3) so they can perform buffer allocations and rendering.

### Mode-Setting
Managing connected monitors and displays and changing the current modes is called Mode-Setting. This is restricted to the current DRM master. Historically, this was implemented in user-space, but new DRM drivers implement a kernel interface to perform mode-setting called Kernel Mode Setting (KMS). If your hardware-driver supports it, you can use the KMS API provided by DRM. This includes allocating framebuffers, selecting modes and managing CRTCs and encoders. See drm-kms(7) for more.

### Memory Management
The most sophisticated tasks for GPUs today is managing memory objects. Textures, framebuffers, command-buffers and all other kinds of commands for the GPU have to be stored in memory. The DRM driver takes care of managing all memory objects, flushing caches, synchronizing access and providing CPU access to GPU memory. All memory management is hardware driver dependent. However, two generic frameworks are available that are used by most DRM drivers. These are the Translation Table Manager (TTM) and the Graphics Execution Manager (GEM). They provide generic APIs to create, destroy and access buffers from user-space. However, there are still many differences between the drivers so driver-dependent code is still needed. Many helpers are provided in libgbm (Graphics Buffer Manager) from the Mesa project. For more information on DRM memory management, see drm-memory(7).

## REPORTING BUGS
Bugs in this manual should be reported to https://gitlab.freedesktop.org/mesa/libdrm/-/issues.

## SEE ALSO
drm-kms(7), drm-memory(7), drmSetMaster(3), drmAuthMagic(3), drmAvailable(3), drmOpen(3)


drm-kms

title: drm-kms(7)

summary: Kernel Mode-Setting

text:
# drm-kms(7)

## NAME
drm-kms - Kernel Mode-Setting

## SYNOPSIS
\#include <xf86drm.h>

\#include <xf86drmMode.h>

## DESCRIPTION
Each DRM device provides access to manage which monitors and displays are currently used and what frames to be displayed. This task is called Kernel Mode-Setting (KMS). Historically, this was done in user-space and called User-space Mode-Setting (UMS). Almost all open-source drivers now provide the KMS kernel API to do this in the kernel, however, many non-open-source binary drivers from different vendors still do not support this. You can use drmModeSettingSupported(3) to check whether your driver supports this. To understand how KMS works, we need to introduce 5 objects: CRTCs, Planes, Encoders, Connectors and Framebuffers.

CRTCs

A CRTC short for CRT Controller is an abstraction representing a part of the chip that contains a pointer to a scanout buffer. Therefore, the number of CRTCs available determines how many independent scanout buffers can be active at any given time. The CRTC structure contains several fields to support this: a pointer to some video memory (abstracted as a frame-buffer object), a list of driven connectors, a display mode and an (x, y) offset into the video memory to support panning or configurations where one piece of video memory spans multiple CRTCs. A CRTC is the central point where configuration of displays happens. You select which objects to use, which modes and which parameters and then configure each CRTC via drmModeCrtcSet(3) to drive the display devices.

Planes

A plane respresents an image source that can be blended with or overlayed on top of a CRTC during the scanout process. Planes are associated with a frame-buffer to crop a portion of the image memory (source) and optionally scale it to a destination size. The result is then blended with or overlayed on top of a CRTC. Planes are not provided by all hardware and the number of available planes is limited. If planes are not available or if not enough planes are available, the user should fall back to normal software blending (via GPU or CPU).

Encoders

An encoder takes pixel data from a CRTC and converts it to a format suitable for any attached connectors. On some devices, it may be possible to have a CRTC send data to more than one encoder. In that case, both encoders would receive data from the same scanout buffer, resulting in a cloned display configuration across the connectors attached to each encoder.

Connectors

A connector is the final destination of pixel-data on a device, and usually connects directly to an external display device like a monitor or laptop panel. A connector can only be attached to one encoder at a time. The connector is also the structure where information about the attached display is kept, so it contains fields for display data, EDID data, DPMS and connection status, and information about modes supported on the attached displays.

Framebuffers

Framebuffers are abstract memory objects that provide a source of pixel data to scanout to a CRTC. Applications explicitly request the creation of framebuffers and can control their behavior. Framebuffers rely on the underneath memory manager for low-level memory operations. When creating a framebuffer, applications pass a memory handle through the API which is used as backing storage. The framebuffer itself is only an abstract object with no data. It just refers to memory buffers that must be created with the drm-memory(7) API.

### Mode-Setting
Before mode-setting can be performed, an application needs to call drmSetMaster(3) to become DRM-Master. It then has exclusive access to the KMS API. A call to drmModeGetResources(3) returns a list of CRTCs, Connectors, Encoders and Planes.

Normal procedure now includes: First, you select which connectors you want to use. Users are mostly interested in which monitor or display-panel is active so you need to make sure to arrange them in the correct logical order and select the correct ones to use. For each connector, you need to find a CRTC to drive this connector. If you want to clone output to two or more connectors, you may use a single CRTC for all cloned connectors (if the hardware supports this). To find a suitable CRTC, you need to iterate over the list of encoders that are available for each connector. Each encoder contains a list of CRTCs that it can work with and you simply select one of these CRTCs. If you later program the CRTC to control a connector, it automatically selects the best encoder. However, this procedure is needed so your CRTC has at least one working encoder for the selected connector. See the Examples section below for more information.

All valid modes for a connector can be retrieved with a call to drmModeGetConnector(3) You need to select the mode you want to use and save it. The first mode in the list is the default mode with the highest resolution possible and often a suitable choice.

After you have a working connector+CRTC+mode combination, you need to create a framebuffer that is used for scanout. Memory buffer allocation is driver-dependent and described in drm-memory(7). You need to create a buffer big enough for your selected mode. Now you can create a framebuffer object that uses your memory-buffer as scanout buffer. You can do this with drmModeAddFB(3) and drmModeAddFB2(3).

As a last step, you want to program your CRTC to drive your selected connector. You can do this with a call to drmModeSetCrtc(3).

### Page-Flipping
A call to drmModeSetCrtc(3) is executed immediately and forces the CRTC to use the new scanout buffer. If you want smooth-transitions without tearing, you probably use double-buffering. You need to create one framebuffer object for each buffer you use. You can then call drmModeSetCrtc(3) on the next buffer to flip. If you want to synchronize your flips with vertical-blanks, you can use drmModePageFlip(3) which schedules your page-flip for the next vblank.

### Planes
Planes are controlled independently from CRTCs. That is, a call to drmModeSetCrtc(3) does not affect planes. Instead, you need to call drmModeSetPlane(3) to configure a plane. This requires the plane ID, a CRTC, a framebuffer and offsets into the plane-framebuffer and the CRTC-framebuffer. The CRTC then blends the content from the plane over the CRTC framebuffer buffer during scanout. As this does not involve any software-blending, it is way faster than traditional blending. However, plane resources are limited. See drmModeGetPlaneResources(3) for more information.

### Cursors
Similar to planes, many hardware also supports cursors. A cursor is a very small buffer with an image that is blended over the CRTC framebuffer. You can set a different cursor for each CRTC with drmModeSetCursor(3) and move it on the screen with drmModeMoveCursor(3). This allows to move the cursor on the screen without rerendering. If no hardware cursors are supported, you need to rerender for each frame the cursor is moved.

## EXAMPLES
Some examples of how basic mode-setting can be done. See the man-page of each DRM function for more information.

### CRTC/Encoder Selection
If you retrieved all display configuration information via drmModeGetResources(3) as drmModeRes *res, selected a connector from the list in res->connectors and retrieved the connector-information as drmModeConnector *conn via drmModeGetConnector(3) then this example shows, how you can find a suitable CRTC id to drive this connector. This function takes a file-descriptor to the DRM device (see drmOpen(3)) as fd, a pointer to the retrieved resources as res and a pointer to the selected connector as conn. It returns an integer smaller than 0 on failure, otherwise, a valid CRTC id is returned.

```
static int modeset_find_crtc(int fd, drmModeRes *res, drmModeConnector *conn)
{

    drmModeEncoder *enc;

    unsigned int i, j;

    /* iterate all encoders of this connector */

    for (i = 0; i < conn->count_encoders; ++i) {

        enc = drmModeGetEncoder(fd, conn->encoders[i]);

        if (!enc) {

            /* cannot retrieve encoder, ignoring... */

            continue;

        }

        /* iterate all global CRTCs */

        for (j = 0; j < res->count_crtcs; ++j) {

            /* check whether this CRTC works with the encoder */

            if (!(enc->possible_crtcs & (1 << j)))

                continue;

            /* Here you need to check that no other connector

             * currently uses the CRTC with id "crtc". If you intend

             * to drive one connector only, then you can skip this

             * step. Otherwise, simply scan your list of configured

             * connectors and CRTCs whether this CRTC is already

             * used. If it is, then simply continue the search here. */

            if (res->crtcs[j] "is unused") {

                drmModeFreeEncoder(enc);

                return res->crtcs[j];

            }

        }

        drmModeFreeEncoder(enc);

    }

    /* cannot find a suitable CRTC */

    return -ENOENT;
}
```

## REPORTING BUGS
Bugs in this manual should be reported to https://gitlab.freedesktop.org/mesa/libdrm/-/issues

## SEE ALSO
drm(7), drm-memory(7), drmModeGetResources(3), drmModeGetConnector(3), drmModeGetEncoder(3), drmModeGetCrtc(3), drmModeSetCrtc(3), drmModeGetFB(3), drmModeAddFB(3), drmModeAddFB2(3), drmModeRmFB(3), drmModePageFlip(3), drmModeGetPlaneResources(3), drmModeGetPlane(3), drmModeSetPlane(3), drmModeSetCursor(3), drmModeMoveCursor(3), drmSetMaster(3), drmAvailable(3), drmCheckModesettingSupported(3), drmOpen(3)


drm-memory

title: drm-memory(7)

summary: DRM Memory Management

text:
# drm-memory(7)

## NAME
drm-memory - DRM Memory Management

## SYNOPSIS
\#include <xf86drm.h>

## DESCRIPTION
Many modern high-end GPUs come with their own memory managers. They even include several different caches that need to be synchronized during access. Textures, framebuffers, command buffers and more need to be stored in memory that can be accessed quickly by the GPU. Therefore, memory management on GPUs is highly driver- and hardware-dependent.

However, there are several frameworks in the kernel that are used by more than one driver. These can be used for trivial mode-setting without requiring driver-dependent code. But for hardware-accelerated rendering you need to read the manual pages for the driver you want to work with.

### Dumb-Buffers
Almost all in-kernel DRM hardware drivers support an API called Dumb-Buffers. This API allows to create buffers of arbitrary size that can be used for scanout. These buffers can be memory mapped via mmap(2) so you can render into them on the CPU. However, GPU access to these buffers is often not possible. Therefore, they are fine for simple tasks but not suitable for complex compositions and renderings.

The DRM_IOCTL_MODE_CREATE_DUMB ioctl can be used to create a dumb buffer. The kernel will return a 32-bit handle that can be used to manage the buffer with the DRM API. You can create framebuffers with drmModeAddFB(3) and use it for mode-setting and scanout. To access the buffer, you first need to retrieve the offset of the buffer. The DRM_IOCTL_MODE_MAP_DUMB ioctl requests the DRM subsystem to prepare the buffer for memory-mapping and returns a fake-offset that can be used with mmap(2).

The DRM_IOCTL_MODE_CREATE_DUMB ioctl takes as argument a structure of type struct drm_mode_create_dumb:

```
struct drm_mode_create_dumb {

    __u32 height;

    __u32 width;

    __u32 bpp;

    __u32 flags;

    __u32 handle;

    __u32 pitch;

    __u64 size;
};
```

The fields height, width, bpp and flags have to be provided by the caller. The other fields are filled by the kernel with the return values. height and width are the dimensions of the rectangular buffer that is created. bpp is the number of bits-per-pixel and must be a multiple of 8. You most commonly want to pass 32 here. The flags field is currently unused and must be zeroed. Different flags to modify the behavior may be added in the future. After calling the ioctl, the handle, pitch and size fields are filled by the kernel. handle is a 32-bit gem handle that identifies the buffer. This is used by several other calls that take a gem-handle or memory-buffer as argument. The pitch field is the pitch (or stride) of the new buffer. Most drivers use 32-bit or 64-bit aligned stride-values. The size field contains the absolute size in bytes of the buffer. This can normally also be computed with (height * pitch + width) * bpp / 4.

To prepare the buffer for mmap(2) you need to use the DRM_IOCTL_MODE_MAP_DUMB ioctl. It takes as argument a structure of type struct drm_mode_map_dumb:

```
struct drm_mode_map_dumb {

    __u32 handle;

    __u32 pad;

    __u64 offset;
};
```

You need to put the gem-handle that was previously retrieved via DRM_IOCTL_MODE_CREATE_DUMB into the handle field. The pad field is unused padding and must be zeroed. After completion, the offset field will contain an offset that can be used with mmap(2) on the DRM file-descriptor.

If you don't need your dumb-buffer, anymore, you have to destroy it with DRM_IOCTL_MODE_DESTROY_DUMB. If you close the DRM file-descriptor, all open dumb-buffers are automatically destroyed. This ioctl takes as argument a structure of type struct drm_mode_destroy_dumb:

```
struct drm_mode_destroy_dumb {

    __u32 handle;
};
```

You only need to put your handle into the handle field. After this call, the handle is invalid and may be reused for new buffers by the dumb-API.

### TTM
TTM stands for Translation Table Manager and is a generic memory-manager provided by the kernel. It does not provide a common user-space API so you need to look at each driver interface if you want to use it. See for instance the radeon man pages for more information on memory-management with radeon and TTM.

### GEM
GEM stands for Graphics Execution Manager and is a generic DRM memory-management framework in the kernel, that is used by many different drivers. GEM is designed to manage graphics memory, control access to the graphics device execution context and handle essentially NUMA environment unique to modern graphics hardware. GEM allows multiple applications to share graphics device resources without the need to constantly reload the entire graphics card. Data may be shared between multiple applications with gem ensuring that the correct memory synchronization occurs.

GEM provides simple mechanisms to manage graphics data and control execution flow within the linux DRM subsystem. However, GEM is not a complete framework that is fully driver independent. Instead, if provides many functions that are shared between many drivers, but each driver has to implement most of memory-management with driver-dependent ioctls. This manpage tries to describe the semantics (and if it applies, the syntax) that is shared between all drivers that use GEM.

All GEM APIs are defined as ioctl(2) on the DRM file descriptor. An application must be authorized via drmAuthMagic(3) to the current DRM-Master to access the GEM subsystem. A driver that does not support GEM will return ENODEV for all these ioctls. Invalid object handles return EINVAL and invalid object names return ENOENT.

Gem provides explicit memory management primitives. System pages are allocated when the object is created, either as the fundamental storage for hardware where system memory is used by the graphics processor directly, or as backing store for graphics-processor resident memory.

Objects are referenced from user-space using handles. These are, for all intents and purposes, equivalent to file descriptors but avoid the overhead. Newer kernel drivers also support the drm-prime (7) infrastructure which can return real file-descriptor for GEM-handles using the linux DMA-BUF API. Objects may be published with a name so that other applications and processes can access them. The name remains valid as long as the object exists. GEM-objects are reference counted in the kernel. The object is only destroyed when all handles from user-space were closed.

GEM-buffers cannot be created with a generic API. Each driver provides its own API to create GEM-buffers. See for example DRM_I915_GEM_CREATE, DRM_NOUVEAU_GEM_NEW or DRM_RADEON_GEM_CREATE. Each of these ioctls returns a GEM-handle that can be passed to different generic ioctls. The libgbm library from the mesa3D distribution tries to provide a driver-independent API to create GBM buffers and retrieve a GBM-handle to them. It allows to create buffers for different use-cases including scanout, rendering, cursors and CPU-access. See the libgbm library for more information or look at the driver-dependent man-pages (for example drm-intel(7) or drm-radeon(7)).

GEM-buffers can be closed with drmCloseBufferHandle(3). It takes as argument the GEM-handle to be closed. After this call the GEM handle cannot be used by this process anymore and may be reused for new GEM objects by the GEM API.

If you want to share GEM-objects between different processes, you can create a name for them and pass this name to other processes which can then open this GEM-object. Names are currently 32-bit integer IDs and have no special protection. That is, if you put a name on your GEM-object, every other client that has access to the DRM device and is authenticated via drmAuthMagic(3) to the current DRM-Master, can guess the name and open or access the GEM-object. If you want more fine-grained access control, you can use the new drm-prime(7) API to retrieve file-descriptors for GEM-handles. To create a name for a GEM-handle, you use the DRM_IOCTL_GEM_FLINK ioctl. It takes as argument a structure of type struct drm_gem_flink:

```
struct drm_gem_flink {

    __u32 handle;

    __u32 name;
};
```

You have to put your handle into the handle field. After completion, the kernel has put the new unique name into the name field. You can now pass this name to other processes which can then import the name with the DRM_IOCTL_GEM_OPEN ioctl. It takes as argument a structure of type struct drm_gem_open:

```
struct drm_gem_open {

    __u32 name;

    __u32 handle;

    __u32 size;
};
```

You have to fill in the name field with the name of the GEM-object that you want to open. The kernel will fill in the handle and size fields with the new handle and size of the GEM-object. You can now access the GEM-object via the handle as if you created it with the GEM API.

Besides generic buffer management, the GEM API does not provide any generic access. Each driver implements its own functionality on top of this API. This includes execution-buffers, GTT management, context creation, CPU access, GPU I/O and more. The next higher-level API is OpenGL. So if you want to use more GPU features, you should use the mesa3D library to create OpenGL contexts on DRM devices. This does not require any windowing-system like X11, but can also be done on raw DRM devices. However, this is beyond the scope of this man-page. You may have a look at other mesa3D man pages, including libgbm and libEGL. 2D software-rendering (rendering with the CPU) can be achieved with the dumb-buffer-API in a driver-independent fashion, however, for hardware-accelerated 2D or 3D rendering you must use OpenGL. Any other API that tries to abstract the driver-internals to access GEM-execution-buffers and other GPU internals, would simply reinvent OpenGL so it is not provided. But if you need more detailed information for a specific driver, you may have a look into the driver-manpages, including drm-intel(7), drm-radeon(7) and drm-nouveau(7). However, the drm-prime(7) infrastructure and the generic GEM API as described here allow display-managers to handle graphics-buffers and render-clients without any deeper knowledge of the GPU that is used. Moreover, it allows to move objects between GPUs and implement complex display-servers that don't do any rendering on their own. See its man-page for more information.

## EXAMPLES
This section includes examples for basic memory-management tasks.

### Dumb-Buffers
This examples shows how to create a dumb-buffer via the generic DRM API. This is driver-independent (as long as the driver supports dumb-buffers) and provides memory-mapped buffers that can be used for scanout. This example creates a full-HD 1920x1080 buffer with 32 bits-per-pixel and a color-depth of 24 bits. The buffer is then bound to a framebuffer which can be used for scanout with the KMS API (see drm-kms(7)).

```
struct drm_mode_create_dumb creq;
struct drm_mode_destroy_dumb dreq;
struct drm_mode_map_dumb mreq;
uint32_t fb;
int ret;
void *map;
/* create dumb buffer */
memset(&creq, 0, sizeof(creq));
creq.width = 1920;
creq.height = 1080;
creq.bpp = 32;
ret = drmIoctl(fd, DRM_IOCTL_MODE_CREATE_DUMB, &creq);
if (ret < 0) {

    /* buffer creation failed; see "errno" for more error codes */

    ...
}
/* creq.pitch, creq.handle and creq.size are filled by this ioctl with

 * the requested values and can be used now. */
/* create framebuffer object for the dumb-buffer */
ret = drmModeAddFB(fd, 1920, 1080, 24, 32, creq.pitch, creq.handle, &fb);
if (ret) {

    /* frame buffer creation failed; see "errno" */

    ...
}
/* the framebuffer "fb" can now used for scanout with KMS */
/* prepare buffer for memory mapping */
memset(&mreq, 0, sizeof(mreq));
mreq.handle = creq.handle;
ret = drmIoctl(fd, DRM_IOCTL_MODE_MAP_DUMB, &mreq);
if (ret) {

    /* DRM buffer preparation failed; see "errno" */

    ...
}
/* mreq.offset now contains the new offset that can be used with mmap() */
/* perform actual memory mapping */
map = mmap(0, creq.size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, mreq.offset);
if (map == MAP_FAILED) {

    /* memory-mapping failed; see "errno" */

    ...
}
/* clear the framebuffer to 0 */
memset(map, 0, creq.size);
```

## REPORTING BUGS
Bugs in this manual should be reported to https://gitlab.freedesktop.org/mesa/libdrm/-/issues

## SEE ALSO
drm(7), drm-kms(7), drm-prime(7), drmAvailable(3), drmOpen(3), drm-intel(7), drm-radeon(7), drm-nouveau(7)