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).

branch: sisyphus


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 pkgconf(1) 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, which is a discouraged way, being 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 pkgconf(1) library named libbsd. The includes in this case should be namespaced with bsd/, such as <bsd/unistd.h>.

The package also provides a libbsd-ctor static library that can be used to inject automatic constructors into a program so that the setproctitle_init(3bsd) function gets invoked automatically at startup time. This can be done with the pkgconf(1) 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>

## VARIANTS
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(3bsd)

strnunvis(3bsd)

NetBSD added strnvis(3bsd) and strnunvis(3bsd) 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(3bsd) 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(3bsd)

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(3bsd)

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(3bsd)

Unportable, requires assistance from the stdio layer or some hook framework. On glibc- and musl-based 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(3bsd)

This function is provided by glibc 2.25, and musl 1.1.20.

reallocarray(3bsd)

This function is provided by glibc 2.26, and musl 1.2.2.

closefrom(3bsd)

This function is provided by glibc 2.34.

arc4random(3bsd)

arc4random_buf(3bsd)

arc4random_uniform(3bsd)

These functions are provided by glibc 2.36. Note that it does not provide the arc4random_stir(3bsd) and arc4random_addrandom(3bsd) functions.

strlcpy(3bsd)

strlcat(3bsd)

These functions are provided by glibc 2.38, and musl 0.5.0.

## 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.

The following information is generic. Some debuginfod clients may internally override defaults listed here.

## 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. This environment variable can also contain policy defining tags which dictate the response policy for verifying per-file IMA signatures in RPMs. As the space seperated list is read left to right, upon encountering a tag, subsequent URLs up to the next tag will be handled using that specified policy. All URLs before the first tag will use the default policy, ima:ignore. For example:

```
DEBUGINFOD_URLS="https://foo.com ima:enforcing https://bar.ca http://localhost:8002/ ima:ignore https://baz.org"

```

Where foo.com and baz.org use the default ignore policy and bar.ca and localhost use an enforcing policy. The policy tag may be one of the following:

ima:enforcing Every downloaded file requires a valid signature, fully protecting integrity.

ima:ignore Skips verification altogether, providing no protection.

Alerts of validation failure will be directed as specified in $DEBUGINFOD_VERBOSE.

$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.

$DEBUGINFOD_IMA_CERT_PATH

This environment variable contains a list of absolute directory paths holding X.509 certificates for RPM per-file IMA-verification. Alternate paths are separated by colons.

## 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".

metadata_retention_s

This control file sets how long to remember the results of a metadata query. New queries for the same artifacts within this time window are short-circuited (repeating the same results). This accelerates queries that probably would probably have the same results. The default is 3600, 1 hour. 0 means "do not retain".


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)


editline

title: editline(7)

summary: line editing user interface

text:
# editline(7)

## NAME
editline — line editing user interface

## DESCRIPTION
When a program using the editline(3) library prompts for an input string using the function el_wgets(3), it reads characters from the terminal. Invalid input bytes that do not form characters are silently discarded. For each character read, one editor command is executed. The mapping of input characters to editor commands depends on the editing mode. There are three editing modes: vi insert mode, vi command mode, and emacs mode. The default is vi insert mode. The program can switch the default to emacs mode by using the el_set(3) or el_parse(3) functions, and the user can switch to emacs mode either in the editrc(5) configuration file or interactively with the ed-command editor command, in all three cases executing the bind -e builtin command.

If trying to read from the terminal results in end of file or an error, the library signals end of file to the program and does not return a string.

### Input character bindings
All default bindings described below can be overridden by individual programs and can be changed with the editrc(5) bind builtin command.

In the following tables, ‘Ctrl-’ indicates a character with the bit 0x40 flipped, and ‘Meta-’ indicates a character with the bit 0x80 set. In vi insert mode and in emacs mode, all Meta-characters considered printable by the current locale(1) are bound to ed-insert instead of to the editor command listed below. Consequently, in UTF-8 mode, most of the Meta-characters are not directly accessible because their code points are occupied by printable Unicode characters, and Meta-characters are usually input using the em-meta-next editor command. For example, to enter ‘Meta-B’ in order to call the ed-prev-word editor command in emacs mode, call em-meta-next by pressing and releasing the escape key (or equivalently, Ctrl-[), then press and release the ‘B’ key. If you have configured a Meta-key on your keyboard, for example with ‘setxkbmap -option altwin:left_meta_win’, the Ctrl-Meta-characters are directly accessible. For example, to enter ‘Ctrl-Meta-H’ in order to call the ed-delete-prev-word editor command in emacs mode, hold down the keys ‘Ctrl’, ‘Meta’, and ‘H’ at the same time. Alternatively, press and release the escape key, then press and release ‘Ctrl-H’.

In vi input mode, input characters are bound to the following editor commands by default:

Ctrl-D, EOF

vi-list-or-eof

Ctrl-H, BS

vi-delete-prev-char

Ctrl-J, LF

ed-newline

Ctrl-M, CR

ed-newline

Ctrl-Q

ed-tty-start-output

Ctrl-S

ed-tty-stop-output

Ctrl-U

vi-kill-line-prev

Ctrl-V

ed-quoted-insert

Ctrl-W

ed-delete-prev-word

Ctrl-[, ESC

vi-command-mode

Ctrl-\, QUIT

ed-tty-sigquit

Ctrl-?, DEL

vi-delete-prev-char

All other input characters except the NUL character (Ctrl-@) are bound to ed-insert.

In vi command mode, input characters are bound to the following editor commands by default:

Ctrl-A

ed-move-to-beg

Ctrl-C, INT

ed-tty-sigint

Ctrl-E

ed-move-to-end

Ctrl-H, BS

ed-delete-prev-char

Ctrl-J, LF

ed-newline

Ctrl-K

ed-kill-line

Ctrl-L, FF

ed-clear-screen

Ctrl-M, CR

ed-newline

Ctrl-N

ed-next-history

Ctrl-O

ed-tty-flush-output

Ctrl-P

ed-prev-history

Ctrl-Q

ed-tty-start-output

Ctrl-R

ed-redisplay

Ctrl-S

ed-tty-stop-output

Ctrl-U

vi-kill-line-prev

Ctrl-W

ed-delete-prev-word

Ctrl-[, ESC

em-meta-next

Ctrl-\, QUIT

ed-tty-sigquit

Space

ed-next-char

\#

vi-comment-out

$

ed-move-to-end

%

vi-match

+

ed-next-history

,

vi-repeat-prev-char

-

ed-prev-history

.

vi-redo

/

vi-search-prev

0

vi-zero

1 to 9

ed-argument-digit

:

ed-command

;

vi-repeat-next-char

?

vi-search-next

@

vi-alias

A

vi-add-at-eol

B

vi-prev-big-word

C

vi-change-to-eol

D

ed-kill-line

E

vi-end-big-word

F

vi-prev-char

G

vi-to-history-line

I

vi-insert-at-bol

J

ed-search-next-history

K

ed-search-prev-history

N

vi-repeat-search-prev

O

ed-sequence-lead-in

P

vi-paste-prev

R

vi-replace-mode

S

vi-substitute-line

T

vi-to-prev-char

U

vi-undo-line

W

vi-next-big-word

X

ed-delete-prev-char

Y

vi-yank-end

[

ed-sequence-lead-in

^

ed-move-to-beg

_

vi-history-word

a

vi-add

b

vi-prev-word

c

vi-change-meta

d

vi-delete-meta

e

vi-end-word

f

vi-next-char

h

ed-prev-char

i

vi-insert

j

ed-next-history

k

ed-prev-history

l

ed-next-char

n

vi-repeat-search-next

p

vi-paste-next

r

vi-replace-char

s

vi-substitute-char

t

vi-to-next-char

u

vi-undo

v

vi-histedit

w

vi-next-word

x

ed-delete-next-char

y

vi-yank

|

vi-to-column

~

vi-change-case

Ctrl-?, DEL

ed-delete-prev-char

Meta-O

ed-sequence-lead-in

Meta-[

ed-sequence-lead-in

In emacs mode, input characters are bound to the following editor commands by default:

0 to 9

ed-digit

Ctrl-@, NUL

em-set-mark

Ctrl-A

ed-move-to-beg

Ctrl-B

ed-prev-char

Ctrl-C, INT

ed-tty-sigint

Ctrl-D, EOF

em-delete-or-list

Ctrl-E

ed-move-to-end

Ctrl-F

ed-next-char

Ctrl-H, BS

em-delete-prev-char

Ctrl-J, LF

ed-newline

Ctrl-K

ed-kill-line

Ctrl-L, FF

ed-clear-screen

Ctrl-M, CR

ed-newline

Ctrl-N

ed-next-history

Ctrl-O

ed-tty-flush-output

Ctrl-P

ed-prev-history

Ctrl-Q

ed-tty-start-output

Ctrl-R

ed-redisplay

Ctrl-S

ed-tty-stop-output

Ctrl-T

ed-transpose-chars

Ctrl-U

ed-kill-line

Ctrl-V

ed-quoted-insert

Ctrl-W

em-kill-region

Ctrl-X

ed-sequence-lead-in

Ctrl-Y

em-yank

Ctrl-Z, TSTP

ed-tty-sigtstp

Ctrl-[, ESC

em-meta-next

Ctrl-\, QUIT

ed-tty-sigquit

Ctrl-]

ed-tty-dsusp

Ctrl-?, DEL

em-delete-prev-char

Ctrl-Meta-H

ed-delete-prev-word

Ctrl-Meta-L

ed-clear-screen

Ctrl-Meta-_

em-copy-prev-word

Meta-0 to 9

ed-argument-digit

Meta-B

ed-prev-word

Meta-C

em-capitol-case

Meta-D

em-delete-next-word

Meta-F

em-next-word

Meta-L

em-lower-case

Meta-N

ed-search-next-history

Meta-O

ed-sequence-lead-in

Meta-P

ed-search-prev-history

Meta-U

em-upper-case

Meta-W

em-copy-region

Meta-X

ed-command

Meta-[

ed-sequence-lead-in

Meta-b

ed-prev-word

Meta-c

em-capitol-case

Meta-d

em-delete-next-word

Meta-f

em-next-word

Meta-l

em-lower-case

Meta-n

ed-search-next-history

Meta-p

ed-search-prev-history

Meta-u

em-upper-case

Meta-w

em-copy-region

Meta-x

ed-command

Ctrl-Meta-?

ed-delete-prev-word

The remaining ascii(7) characters in the range 0x20 to 0x7e are bound to ed-insert.

If standard output is not connected to a terminal device or el_set(3) was used to set EL_EDITMODE to 0, all input character bindings are disabled and all characters typed are appended to the edit buffer. In that case, the edit buffer is returned to the program after a newline or carriage return character is typed, or after the first character typed if el_set(3) was used to set EL_UNBUFFERED to non-zero.

### Editor commands
Most editor commands accept an optional argument. The argument is entered by prefixing the editor command with one or more of the editor commands ed-argument-digit, ed-digit, em-universal-argument, or vi-zero. When an argument is not provided, it defaults to 1. For most editor commands, the effect of an argument is to repeatedly execute the command that number of times.

When talking about a character string from a left character to a right character, the left character is included in the string, while the right character is not included.

If an editor command causes an error, the input character is discarded, no action occurs, and the terminal bell is rung. In case of a non-fatal error, the terminal bell is also rung, but the editor command takes effect anyway.

In the following list, the default key bindings are listed after each editor command.

ed-argument-digit (vi command: 1 to 9; emacs: Meta-0 to Meta-9)

If in argument input mode, append the input digit to the argument being read. Otherwise, switch to argument input mode and use the input digit as the most significant digit of the argument. It is an error if the input character is not a digit or if the existing argument is already greater than a million.

ed-clear-screen (vi command: Ctrl-L; emacs: Ctrl-L, Ctrl-Meta-L)

Clear the screen and display the edit buffer at the top. Ignore any argument.

ed-command (vi command: ‘:’; emacs: Meta-X, Meta-x)

Read a line from the terminal bypassing the normal line editing functionality and execute that line as an editrc(5) builtin command. If in vi command mode, also switch back to vi insert mode. Ignore any argument.

ed-delete-next-char (vi command: x)

Delete the character at the cursor position. With an argument, delete that number of characters. In emacs mode, it is an error if the cursor is at the end of the edit buffer. In vi mode, the last character in the edit buffer is deleted in that case, and it is an error if the buffer is empty.

ed-delete-prev-char (vi command: X, Ctrl-H, BS, Ctrl-?, DEL)

Delete the character to the left of the cursor position. With an argument, delete that number of characters. It is an error if the cursor is at the beginning of the edit buffer.

ed-delete-prev-word (vi: Ctrl-W; emacs: Ctrl-Meta-H, Ctrl-Meta-?)

Move to the left to the closest beginning of a word, delete the string from that position to the cursor, and save it to the cut buffer. With an argument, delete that number of words. It is an error if the cursor is at the beginning of the edit buffer.

ed-digit (emacs: 0 to 9)

If in argument input mode, append the input digit to the argument being read. Otherwise, call ed-insert. It is an error if the input character is not a digit or if the existing argument is already greater than a million.

ed-end-of-file (not bound by default)

Discard the edit buffer and indicate end of file to the program. Ignore any argument.

ed-ignore (various)

Discard the input character and do nothing.

ed-insert (vi input: almost all; emacs: printable characters)

In insert mode, insert the input character left of the cursor position. In replace mode, overwrite the character at the cursor and move the cursor to the right by one character position. Accept an argument to do this repeatedly. It is an error if the input character is the NUL character (Ctrl-@). Failure to enlarge the edit buffer also results in an error.

ed-kill-line (vi command: D, Ctrl-K; emacs: Ctrl-K, Ctrl-U)

Delete the string from the cursor position to the end of the line and save it to the cut buffer. Ignore any argument.

ed-move-to-beg (vi command: ^, Ctrl-A; emacs: Ctrl-A)

In vi mode, move the cursor to the first non-space character in the edit buffer. In emacs mode, move the cursor to the beginning of the edit buffer. Ignore any argument. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank.

ed-move-to-end (vi command: $, Ctrl-E; emacs: Ctrl-E)

Move the cursor to the end of the edit buffer. Ignore any argument. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank.

ed-newline (all modes: Ctrl-J, LF, Ctrl-M, CR)

Append a newline character to the edit buffer and return the edit buffer to the program. Ignore any argument.

ed-next-char (vi command: Space, l; emacs: Ctrl-F)

Move the cursor one character position to the right. With an argument, move by that number of characters. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the end of the edit buffer.

ed-next-history (vi command: j, +, Ctrl-N; emacs: Ctrl-N)

Replace the edit buffer with the next history line. That line is older than the current line. With an argument, go forward by that number of history lines. It is a non-fatal error to advance by more lines than are available.

ed-next-line (not bound by default)

Move the cursor down one line. With an argument, move down by that number of lines. It is an error if the edit buffer does not contain enough newline characters to the right of the cursor position.

ed-prev-char (vi command: h; emacs: Ctrl-B)

Move the cursor one character position to the left. With an argument, move by that number of characters. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the beginning of the edit buffer.

ed-prev-history (vi command: k, -, Ctrl-P; emacs: Ctrl-P)

Replace the edit buffer with the previous history line. That line is newer than the current line. With an argument, go back by that number of lines. It is a non-fatal error to back up by more lines than are available.

ed-prev-line (not bound by default)

Move the cursor up one line. With an argument, move up by that number of lines. It is an error if the edit buffer does not contain enough newline characters to the left of the cursor position.

ed-prev-word (emacs: Meta-B, Meta-b)

Move the cursor to the left to the closest beginning of a word. With an argument, repeat that number of times. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the beginning of the edit buffer.

ed-quoted-insert (vi insert, emacs: Ctrl-V)

Read one character from the terminal bypassing the normal line editing functionality and call ed-insert on it. If trying to read the character returns end of file or an error, call ed-end-of-file instead.

ed-redisplay (vi command, emacs: Ctrl-R)

Redisplay everything. Ignore any argument.

ed-search-next-history (vi command: J; emacs: Meta-N, Meta-n)

Replace the edit buffer with the next matching history entry.

ed-search-prev-history (vi command: K; emacs: Meta-P, Meta-p)

Replace the edit buffer with the previous matching history entry.

ed-sequence-lead-in (vi cmd: O, [; emacs: Ctrl-X; both: Meta-O, Meta-[)

Call a macro. See the section about Macros below for details.

ed-start-over (not bound by default)

Discard the contents of the edit buffer and start from scratch. Ignore any argument.

ed-transpose-chars (emacs: Ctrl-T)

Exchange the character at the cursor position with the one to the left of it and move the cursor to the character to the right of the two exchanged characters. Ignore any argument. It is an error if the cursor is at the beginning of the edit buffer or if the edit buffer contains less than two characters.

ed-unassigned (all characters not listed)

This editor command always results in an error.

em-capitol-case (emacs: Meta-C, Meta-c)

Capitalize the string from the cursor to the end of the current word. That is, if it contains at least one alphabetic character, convert the first alphabetic character to upper case, and convert all characters to the right of it to lower case. In any case, move the cursor to the next character after the end of the current word.

em-copy-prev-word (emacs: Ctrl-Meta-_)

Copy the string from the beginning of the current word to the cursor and insert it to the left of the cursor. Move the cursor to the character after the inserted string. It is an error if the cursor is at the beginning of the edit buffer.

em-copy-region (emacs: Meta-W, Meta-w)

Copy the string from the cursor to the mark to the cut buffer. It is an error if the mark is not set.

em-delete-next-word (emacs: Meta-D, Meta-d)

Delete the string from the cursor to the end of the current word and save it to the cut buffer. It is an error if the cursor is at the end of the edit buffer.

em-delete-or-list (emacs: Ctrl-D, EOF)

If the cursor is not at the end of the line, delete the character at the cursor. If the edit buffer is empty, indicate end of file to the program. It is an error if the cursor is at the end of the edit buffer and the edit buffer is not empty.

em-delete-prev-char (emacs: Ctrl-H, BS, Ctrl-?, DEL)

Delete the character to the left of the cursor. It is an error if the cursor is at the beginning of the edit buffer.

em-exchange-mark (not bound by default)

Exchange the cursor and the mark.

em-gosmacs-transpose (not bound by default)

Exchange the two characters to the left of the cursor. It is an error if the cursor is on the first or second character of the edit buffer.

em-inc-search-next (not bound by default)

Emacs incremental next search.

em-inc-search-prev (not bound by default)

Emacs incremental reverse search.

em-kill-line (not bound by default)

Delete the entire contents of the edit buffer and save it to the cut buffer.

em-kill-region (emacs: Ctrl-W)

Delete the string from the cursor to the mark and save it to the cut buffer. It is an error if the mark is not set.

em-lower-case (emacs: Meta-L, Meta-l)

Convert the characters from the cursor to the end of the current word to lower case.

em-meta-next (vi command, emacs: Ctrl-[, ESC)

Set the bit 0x80 on the next character typed. Unless the resulting code point is printable, holding down the ‘Meta-’ key while typing that character is a simpler way to achieve the same effect.

em-next-word (Meta-F, Meta-f)

Move the cursor to the end of the current word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the end of the edit buffer.

em-set-mark (emacs: Ctrl-Q, NUL)

Set the mark at the current cursor position.

em-toggle-overwrite (insert)

Switch from insert to overwrite mode or vice versa.

em-universal-argument (not bound by default)

If in argument input mode, multiply the argument by 4. Otherwise, switch to argument input mode and set the argument to 4. It is an error if the existing argument is already greater than a million.

em-upper-case (emacs: Meta-U, Meta-u)

Convert the characters from the cursor to the end of the current word to upper case.

em-yank (emacs: Ctrl-Y)

Paste the cut buffer to the left of the cursor.

vi-add (vi command: a)

Switch to vi insert mode. Unless the cursor is already at the end of the edit buffer, move it one character position to the right.

vi-add-at-eol (vi command: A)

Switch to vi insert mode and move the cursor to the end of the edit buffer.

vi-alias (vi command: @)

If an alias function was defined by calling the el_set(3) or el_wset(3) function with the argument EL_ALIAS_TEXT, read one character from the terminal bypassing the normal line editing functionality, call the alias function passing the argument that was specified with EL_ALIAS_TEXT as the first argument and the character read, with an underscore prepended, as the second argument, and pass the string returned from the alias function to el_wpush(3). It is an error if no alias function is defined or if trying to read the character results in end of file or an error.

vi-change-case (vi command: ~)

Change the case of the character at the cursor and move the cursor one character position to the right. It is an error if the cursor is already at the end of the edit buffer.

vi-change-meta (vi command: c)

Delete the string from the cursor to the position specified by the following movement command and save a copy of it to the cut buffer. When given twice in a row, instead delete the whole contents of the edit buffer and save a copy of it to the cut buffer. In either case, switch to vi insert mode after that.

vi-change-to-eol (vi command: C)

Delete the string from the cursor position to the end of the line and save it to the cut buffer, then switch to vi insert mode.

vi-command-mode (vi insert: Ctrl-[, ESC)

Discard pending actions and arguments and switch to vi command mode. Unless the cursor is already at the beginning of the edit buffer, move it to the left by one character position.

vi-comment-out (vi command: #)

Insert a ‘#’ character at the beginning of the edit buffer and return the edit buffer to the program.

vi-delete-meta (vi command: d)

Delete the string from the cursor to the position specified by the following movement command and save a copy of it to the cut buffer. When given twice in a row, instead delete the whole contents of the edit buffer and save a copy of it to the cut buffer.

vi-delete-prev-char (vi insert: Ctrl-H, BS, Ctrl-?, DEL)

Delete the character to the left of the cursor. It is an error if the cursor is already at the beginning of the edit buffer.

vi-end-big-word (vi command: E)

Move the cursor to the end of the current space delimited word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the end of the edit buffer.

vi-end-word (vi command: e)

Move the cursor to the end of the current word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the end of the edit buffer.

vi-history-word (vi command: _)

Insert the first word from the most recent history entry after the cursor, move the cursor after to the character after the inserted word, and switch to vi insert mode. It is an error if there is no history entry or the most recent history entry is empty.

vi-insert (vi command: i)

Enter insert mode.

vi-insert-at-bol (vi command: I)

Move the cursor to the beginning of the edit buffer and switch to vi insert mode.

vi-kill-line-prev (vi: Ctrl-U)

Delete the string from the beginning of the edit buffer to the cursor and save it to the cut buffer.

vi-list-or-eof (vi insert: Ctrl-D, EOF)

If the edit buffer is empty, indicate end of file to the program. It is an error if the edit buffer is not empty.

vi-match (vi command: %)

Consider opening and closing parentheses, braces, and brackets as delimiters. If the cursor is not at a delimiter, move it to the right until it gets to one, then move it to the matching delimiter. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if there is no delimiter at the cursor or in the string to the right of the cursor, or if the first such delimiter has no matching delimiter.

vi-next-big-word (vi command: W)

Move the cursor to the right to the beginning of the next space delimited word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the end of the edit buffer or on its last character.

vi-next-char (vi command: f)

Read one character from the terminal bypassing the normal line editing functionality and move the cursor to the right to the next instance of that character in the edit buffer. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. If trying to read the character results in end of file or an error, call ed-end-of-file instead. It is an error if the character is not found searching to the right in the edit buffer.

vi-next-word (vi command: w)

Move the cursor to the right to the beginning of the next word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the end of the edit buffer or on its last character.

vi-paste-next (vi command: p)

Insert a copy of the cut buffer to the right of the cursor. It is an error if the cut buffer is empty.

vi-paste-prev (vi command: P)

Insert a copy of the cut buffer to the left of the cursor. It is an error if the cut buffer is empty.

vi-prev-big-word (vi command: B)

Move the cursor to the left to the next beginning of a space delimited word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the beginning of the edit buffer.

vi-prev-char (vi command: F)

Read one character from the terminal bypassing the normal line editing functionality and move the cursor to the left to the next instance of that character in the edit buffer. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. If trying to read the character results in end of file or an error, call ed-end-of-file instead. It is an error if the character is not found searching to the left in the edit buffer.

vi-prev-word (vi command: b)

Move the cursor to the left to the next beginning of a word. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. It is an error if the cursor is already at the beginning of the edit buffer.

vi-redo (vi command: ‘.’)

Redo the last non-motion command.

vi-repeat-next-char (vi command: ‘;’)

Repeat the most recent character search in the same search direction. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank.

vi-repeat-prev-char (vi command: ‘,’)

Repeat the most recent character search in the opposite search direction. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank.

vi-repeat-search-next (vi command: n)

Repeat the most recent history search in the same search direction.

vi-repeat-search-prev (vi command: N)

Repeat the most recent history search in the opposite search direction.

vi-replace-char (vi command: r)

Switch to vi replace mode, and automatically switch back to vi command mode after the next character typed. See ed-insert for a description of replace mode. It is an error if the cursor is at the end of the edit buffer.

vi-replace-mode (vi command: R)

Switch to vi replace mode. This is a variant of vi insert mode; see ed-insert for the difference.

vi-search-next (vi command: ?)

Replace the edit buffer with the next matching history entry.

vi-search-prev (vi command: /)

Replace the edit buffer with the previous matching history entry.

vi-substitute-char (vi command: s)

Delete the character at the cursor and switch to vi insert mode.

vi-substitute-line (vi command: S)

Delete the entire contents of the edit buffer, save a copy of it in the cut buffer, and enter vi insert mode.

vi-to-column (vi command: |)

Move the cursor to the column specified as the argument. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank.

vi-to-history-line (vi command: G)

Replace the edit buffer with the specified history entry.

vi-to-next-char (vi command: t)

Read one character from the terminal bypassing the normal line editing functionality and move the cursor to the right to the character before the next instance of that character in the edit buffer. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. If trying to read the character results in end of file or an error, call ed-end-of-file instead. It is an error if the character is not found searching to the right in the edit buffer.

vi-to-prev-char (vi command: T)

Read one character from the terminal bypassing the normal line editing functionality and move the cursor to the left to the character after the next instance of that character in the edit buffer. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank. If trying to read the character results in end of file or an error, call ed-end-of-file instead. It is an error if the character is not found searching to the left in the edit buffer.

vi-undo (vi command: u)

Undo the last change.

vi-undo-line (vi command: U)

Undo all changes to the edit buffer.

vi-yank (vi command: y)

Copy the string from the cursor to the position specified by the following movement command to the cut buffer. When given twice in a row, instead copy the whole contents of the edit buffer to the cut buffer.

vi-yank-end (vi command: Y)

Copy the string from the cursor to the end of the edit buffer to the cut buffer.

vi-zero (vi command: 0)

If in argument input mode, multiply the argument by ten. Otherwise, move the cursor to the beginning of the edit buffer. Can be used as a movement command after vi_change_meta, vi_delete_meta, or vi_yank.

### Macros
If an input character is bound to the editor command ed-sequence-lead-in, editline attempts to call a macro. If the input character by itself forms the name of a macro, that macro is executed. Otherwise, additional input characters are read until the string read forms the name of a macro, in which case that macro is executed, or until the string read matches the beginning of none of the existing macro names, in which case the string including the final, mismatching character is discarded and the terminal bell is rung.

There are two kinds of macros. Command macros execute a single editor command. Keyboard macros return a string of characters that is appended as a new line to the Input Queue.

The following command macros are defined by default in vi command mode and in emacs mode:

Esc [ A, Esc O A

ed-prev-history

Esc [ B, Esc O B

ed-next-history

Esc [ C, Esc O C

ed-next-char

Esc [ D, Esc O D

ed-prev-char

Esc [ F, Esc O F

ed-move-to-end

Esc [ H, Esc O H

ed-move-to-beg

In vi command mode, they are also defined by default without the initial escape character.

In addition, the editline library tries to bind the strings generated by the arrow keys as reported by the terminfo(5) database to these editor commands, unless that would clobber user settings.

In emacs mode, the two-character string “Ctrl-X Ctrl-X” is bound to the em-exchange-mark editor command.

### Input Queue
The editline library maintains an input queue operated in FIFO mode. Whenever it needs an input character, it takes the first character from the first line of the input queue. When the queue is empty, it reads from the terminal.

A line can be appended to the end of the input queue in several ways:

- By calling one of the keyboard Macros.

- By calling the editor command vi-redo.

- By calling the editor command vi-alias.

- By pressing a key in emacs incremental search mode that doesn't have a special meaning in that mode but returns to normal emacs mode.

- If an application program directly calls the functions el_push(3) or el_wpush(3), it can provide additional, program-specific ways of appending to the input queue.

## SEE ALSO
mg(1), vi(1), editline(3), el_wgets(3), el_wpush(3), el_wset(3), editrc(5)

## HISTORY
This manual page first appeared in OpenBSD 6.0 and NetBSD 8.

## AUTHORS
This manual page was written by Ingo Schwarze <schwarze@openbsd.org>.