---
name: "termkey_strfkey"
section: "3"
platform: "linux"
package: "libtermkey-dev"
version: "0.22-2+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/termkey_strfkey"
---

# termkey\_strfkey(3)

format a string representing a key event

## NAME

termkey\_strfkey - format a string representing a key event

## SYNOPSIS

```
#include <termkey.h>

size_t termkey_strfkey(TermKey *tk, char *buffer, size_t len,
            TermKeyKey *key, TermKeyFormat format);
```

Link with *-ltermkey*.

## DESCRIPTION

**termkey\_strfkey**() formats a string buffer to contain a human-readable representation of a key event. It fills the *buffer* in a way analogous to the [**snprintf**(3)](/snprintf/3.md) or [**strftime**(3)](/strftime/3.md) standard library functions. This function used to be called **termkey\_snprint\_key**() but was renamed after version 0.6.

The *format* argument specifies the format of the output, as a bitmask of the following constants:

- **TERMKEY\_FORMAT\_LONGMOD**

  Print full modifier names e.g. "`Shift-`" instead of abbreviating to "`S-`".

- **TERMKEY\_FORMAT\_CARETCTRL**

  If the only modifier is **TERMKEY\_MOD\_CTRL** on a plain letter, render it as "`^X`" rather than "`Ctrl-X`".

- **TERMKEY\_FORMAT\_ALTISMETA**

  Use the name "`Meta`" or the letter "`M`" instead of "`Alt`" or "`A`".

- **TERMKEY\_FORMAT\_WRAPBRACKET**

  If the key event is a special key instead of unmodified Unicode, wrap it in "`<brackets>`".

- **TERMKEY\_FORMAT\_SPACEMOD**

  Use spaces instead of hyphens to separate the modifier name(s) from the base key name.

- **TERMKEY\_FORMAT\_LOWERMOD**

  Use lowercase for the modifier name.

- **TERMKEY\_FORMAT\_LOWERSPACE**

  Use lowercase with spaces in for the key name instead of camelCase (for example "`page down`" instead of "`PageDown`").

- **TERMKEY\_FORMAT\_MOUSE\_POS**

  If the event is a mouse event, include the position rendered as "`@ (col,line)`".

The following shortcuts are provided for common combinations of format bits:

- **TERMKEY\_FORMAT\_VIM**

  Shortcut to set **ALTISMETA** and **WRAPBRACKET**, to give an output close to the format the *vim* editor uses.

- **TERMKEY\_FORMAT\_URWID**

  Shortcut to set **ALTISMETA**, **LONGMOD**, **LOWERMOD**, **SPACEMOD** and **LOWERSPACE**, to give an output close to the format the *urwid* python library uses.

When formatting a **TERMKEY\_TYPE\_UNICODE** key structure, this function uses the *utf8* member. If this member contains an empty string (i.e. its first character is 0) then this member will be prefilled by the function from the *code.number* member. This can be convenient when the key structure is being constructed programmatically by user code.

## RETURN VALUE

**termkey\_strfkey**() returns the number of characters written to *buffer*.

## SEE ALSO

[**termkey\_new**(3)](/termkey_new/3.md), [**termkey\_getkey**(3)](/termkey_getkey/3.md), [**termkey\_waitkey**(3)](/termkey_waitkey/3.md), [**termkey\_get\_keyname**(3)](/termkey_get_keyname/3.md), [**termkey\_strpkey**(3)](/termkey_strpkey/3.md), [**termkey**(7)](/termkey/7.md)