YASCREEN(3)

📦
version 2.14 · 7 versions
, in epel 10, epel 9, fedora 43, fedora 44, ubuntu stonking

💖 YASCREEN(3) — the yascreen manual, bestie edition 💖

User-Manual · YASCREEN(3)

✨ NAME ✨

yascreen — Yet Another Screen Library (aka your new fave curses replacement for daemons and embedded apps 🫶)

🌸 SYNOPSIS 🌸

#include <yascreen.h>

🦋 DESCRIPTION 🦋

👑 Main features

okay so here's the whole vibe, no cap:

  • tiny footprint, she's smol 💅
  • zero external dependencies — she doesn't need anybody
  • both internal and external event loops are supported, pick your fighter
  • works with stdin/stdout or external input/output (yes bestie, she can literally run over a socket 🔥)
  • supports a basic set of telnet sequences, which makes her perfect for built-in terminal interfaces for daemons
  • supports a limited set of input keystroke sequences
  • fully unicode compatible (tho parts of this depend on wcwidth in libc, just so you know)
  • utf8 verification of input? supported ✨
  • utf8 input and wide character input? also supported ✨
  • non-utf8 input mode? yup, that too
  • relies only on a limited subset of ansi/xterm ESC sequences, so she plays nice with basically all modern terminals (inspired by linenoise ⟨https://github.com/antirez/linenoise⟩)
  • there is no curses API and no ancient terminal compatibility, hence less bloat — we don't do that here
  • there is no autoconf — there is no need to have one, periodt
  • clean API with opaque private data, usable from C/C++ 🎀
  • easy cross compilation setup (just by setting CC, AR and RANLIB)

Current development is done on Linux, with additional testing on OpenBSD/FreeBSD; other platforms may need minimal fixes.

On *BSD a gmake is required to build. not optional, bestie 😭

🧚 Architecture

yascreen uses an opaque data structure, allocated by the library and dynamically resized when needed — that's yascreen_init(int sx, int sy) / yascreen_resize(yascreen *s, int sx, int sy). An application may specify (0,0) for both calls to let yascreen detect the size, or use a fixed size. In case the terminal has zero size or does not support the TIOCGWINSZ ioctl, the size will default to 80x24.

There are two modes of operation — telnet protocol over socket or running in terminal. For sockets the event loop would typically be handled outside of the library, while for terminals a built-in event loop may be used.

Modes of operation can be modified at runtime. ✨

For terminal use, signal handling (SIGWINCH) should always be handled by the application. always always, don't skip this one 💀

🍓 Example initialization for terminal and handling of SIGWINCH

yascreen *s;
int winch=0;

void sigwinch(int sign) {
     winch=1;
}

s=yascreen_init(0,0); // let yascreen get term size
yascreen_term_set(s,YAS_NOBUFF|YAS_NOSIGN|YAS_NOECHO);
signal(SIGWINCH,sigwinch);

for (;;) { // main loop
     if (winch) {
          winch=0;
          if (yascreen_resize(s,0,0))
               // handle a fatal error - no memory
          // get the new sizes and redraw
          newsizex=yascreen_sx(s);
          newsizey=yascreen_sy(s);
     }

     …
     // option 1

     // input is handled in external event loop and fed to yascreen via yascreen_feed
     if (FD_ISSET(STDIN_FILENO,&r)&&sizeof c==read(STDIN_FILENO,&c,sizeof c))
          yascreen_feed(s,c); // pump state machine with bytestream

     // keys are processed only when available without delay/blocking
     while ((ch=yascreen_getch_nowait(s))!=YAS_K_NONE) {
          // handle processed keys
     }

     …
     // option 2

     // input is handled by yascreen and key or YAS_K_NONE is returned not longer than TIMEOUT ms
     // note: if screen update is based on this, keypresses will force it
     while ((ch=yascreen_getch_to(s,TIMEOUT))!=YAS_K_NONE) {
          // handle processed keys
     }

     …
     // option 3

     // input is handled by yascreen and the following call will block until a key is pressed
     if ((ch=yascreen_getch(s))!=YAS_K_NONE) {
          // handle processed key
     }
}

For sockets, input is handled like option 1 in the example above, and yascreen needs to be provided with a callback for output.

In multiprocess mode daemons where stdin/stdout are redirected to a socket, the same model from the example above can be used. Obviously SIGWINCH will work only for terminals, and for sockets the screen size can get to be known either via telnet or ASNI sequences.

🌈 Example initialization for socket with external event loop and telnet sequences processing

yascreen *s;

s=yascreen_init(80,25); // there is no guarantee that screen size detection is supported on the remote end
yascreen_setout(s,output_cb); // set callback for output
yascreen_set_telnet(s,1); // enable processing of telnet sequences
yascreen_init_telnet(s); // try to negotiate telnet options (regardless if telnet processing is enabled)
yascreen_reqsize(s); // request initial screen size
for (;;) { // main loop
     …
     yascreen_feed(s,c); // feed input from the socket to yascreen

     // keys are processed only when available without delay/blocking
     while ((ch=yascreen_getch_nowait(s))!=YAS_K_NONE) {
          // handle processed keys

          // screen size change is reported as a special keypress code:
          if (ch==YAS_TELNET_SIZE||ch==YAS_SCREEN_SIZE) // screen size change reported via telnet or ANSI sequence
               // redraw
     }
}

💅 API Reference 💅

🎀 Predefined constants and Helper macros

Internally, style is kept into bitfields in a single integer variable — and that includes foreground/background colors plus style modifiers (bold, italic, underline, inverse and blink).

⭐ Style codes

  • YAS_ITALIC — italic
  • YAS_UNDERL — underline
  • YAS_STRIKE — strikeout
  • YAS_INVERSE — inverse
  • YAS_BOLD — bold
  • YAS_BLINK — blink

🌸 Color codes

  • YAS_BLACK — black
  • YAS_RED — red
  • YAS_GREEN — green
  • YAS_YELLOW — yellow
  • YAS_BLUE — blue
  • YAS_MAGENTA — magenta
  • YAS_CYAN — cyan
  • YAS_WHITE — white
  • YAS_FGCOLORDEF — default terminal foreground
  • YAS_BGCOLORDEF — default terminal background

🦋 Helper macros

  • YAS_FG(attribute) — extract foreground color
  • YAS_BG(attribute) — extract background color
  • YAS_FGCOLOR(color) — shift simple color value into foreground color
  • YAS_BGCOLOR(color) — shift simple color value into background color
  • YAS_FGXCOLOR(color) — shift 256 palette color value into foreground color
  • YAS_BGXCOLOR(color) — shift 256 palette color value into background color

All of the above can be or'ed into attribute, provided that the bits for foreground/background color are all zeroes. 👑

🔑 Key codes

  • Special, generated internally

Okay so real talk, bestie — previous versions of the library used -1 and 0x100+ for these codes. But to get that unicode wide character compatibility and a simpler API, the reserved Unicode range 0xf0000-0xffffd is now used for the special codes, both in narrow and wide character input modes. 💅

There's a macro YAS_IS_CC(code) that will evaluate to non-zero for the special codes and to zero for normal characters. Note that all ASCII control characters in the range 0x00-0x7f are treated as normal ones. No cap. 🧚

Here's the special-codes vibe check:

  • YAS_K_NONE — 0xf0000 — no key is available; in time limited mode means that the time limit expired 💀
  • YAS_SCREEN_SIZE — 0xf0701 — notification for screen size change (may come because of telnet or ANSI sequence) 🦋
  • YAS_TELNET_SIZE — 0xf0702 — notification for a possible screen size change, reported via telnet without valid size data; the size should be redetected (e.g. with yascreen_reqsize) 👑
  • Normal keys ✨
  • YAS_K_NUL (0x00) — the Nul key, bestie. on some terminals that's Ctrl-2 💀
  • YAS_K_C_A (0x01) — Ctrl-A ✨
  • YAS_K_C_B (0x02) — Ctrl-B
  • YAS_K_C_C (0x03) — Ctrl-C
  • YAS_K_C_D (0x04) — Ctrl-D
  • YAS_K_C_E (0x05) — Ctrl-E
  • YAS_K_C_F (0x06) — Ctrl-F
  • YAS_K_C_G (0x07) — Ctrl-G
  • YAS_K_C_H (0x08) — Ctrl-H, but ngl it depends on the terminal 🙈 go look at YAS-K-BSP and YAS-K-C-8 for the whole situation
  • YAS_K_C_I (0x09) — Ctrl-I
  • YAS_K_TAB (0x09) — Tab 🎀 (same byte as above, iconic twin behaviour)
  • YAS_K_C_J (0x0a) — Ctrl-J
  • YAS_K_C_K (0x0b) — Ctrl-K
  • YAS_K_C_L (0x0c) — Ctrl-L
  • YAS_K_C_M (0x0d) — Enter, Return, Ctrl-M; peep below for the tea 👀
  • YAS_K_RET (0x0d) — Enter, Return, Ctrl-M; see above, it's the same vibe 🫶
  • YAS_K_C_N (0x0e) — Ctrl-N
  • YAS_K_C_O (0x0f) — Ctrl-O
  • YAS_K_C_P (0x10) — Ctrl-P
  • YAS_K_C_Q (0x11) — Ctrl-Q
  • YAS_K_C_R (0x12) — Ctrl-R
  • YAS_K_C_S (0x13) — Ctrl-S
  • YAS_K_C_T (0x14) — Ctrl-T
  • YAS_K_C_U (0x15) — Ctrl-U
  • YAS_K_C_V (0x16) — Ctrl-V
  • YAS_K_C_W (0x17) — Ctrl-W
  • YAS_K_C_X (0x18) — Ctrl-X
  • YAS_K_C_Y (0x19) — Ctrl-Y
  • YAS_K_C_Z (0x1a) — Ctrl-Z
  • YAS_K_ESC (0x1b) — Esc, Ctrl-3; see below 👇 every single ANSI sequence starts with Esc, and this is what gets returned after a timeout or a double Esc ⏳
  • YAS_K_C_3 (0x1b) — Esc, Ctrl-3; see above 👆 all ANSI sequences start with Esc, and this is returned after a timeout or double Esc, same as its twin 💅
  • YAS_K_C_4 (0x1c) — Ctrl-4
  • YAS_K_C_5 (0x1d) — Ctrl-5
  • YAS_K_C_6 (0x1e) — Ctrl-6
  • YAS_K_C_7 (0x1f) — Ctrl-7
  • YAS_K_SPACE (0x20) — Space 🌸
  • YAS_K_EXCL (0x21) — !
  • YAS_K_DQUOT (0x22) — "
  • YAS_K_HASH (0x23) — #
  • YAS_K_POUND (0x24) — $
  • YAS_K_PERC (0x25) — %
  • YAS_K_AND (0x26) — Ampersand
  • YAS_K_QUOT (0x27) — '
  • YAS_K_OBRA (0x28) — ( -
  • YAS_K_CBRA — 0x29, that's your ) right curly baby 🎀
  • YAS_K_STAR — 0x2a, the * asterisk bestie ✨
  • YAS_K_PLUS — 0x2b, + plus, iconic 💅
  • YAS_K_COMMA — 0x2c, , comma, yes she pauses ✋
  • YAS_K_MINUS — 0x2d, - minus, lowkey underrated
  • YAS_K_DOT — 0x2e, . periodt. literally periodt 💀
  • YAS_K_SLASH — 0x2f, / forward slash, main character of every path 🦋
  • YAS_K_0 — 0x30, the 0 key 🌸
  • YAS_K_1 — 0x31, the 1 key 🌸
  • YAS_K_2 — 0x32, the 2 key 🌸
  • YAS_K_3 — 0x33, the 3 key 🌸
  • YAS_K_4 — 0x34, the 4 key 🌸
  • YAS_K_5 — 0x35, the 5 key 🌸
  • YAS_K_6 — 0x36, the 6 key 🌸
  • YAS_K_7 — 0x37, the 7 key 🌸
  • YAS_K_8 — 0x38, the 8 key 🌸
  • YAS_K_9 — 0x39, the 9 key 🌸
  • YAS_K_COLON — 0x3a, : colon, it's giving explaining things 💜
  • YAS_K_SEMI — 0x3b, ; semicolon, the C programmer's roman empire 😭
  • YAS_K_LT — 0x3c, < less-than, redirecting ur vibes 🫶
  • YAS_K_EQ — 0x3d, Equal ⭐ (yes bestie, the table literally just says Equal, no = glyph, and we respect the source 💖)
  • YAS_K_GT — 0x3e, > greater-than, the other half of every redirect 🔥
  • YAS_K_QUEST — 0x3f, ? question mark, curious girly 🔍
  • YAS_K_AT — 0x40, @ at sign, tagging everyone in the group chat 📣
  • YAS_K_A — 0x41, A 👑
  • YAS_K_B — 0x42, B 👑
  • YAS_K_C — 0x43, C 👑
  • YAS_K_D — 0x44, D 👑
  • YAS_K_E — 0x45, E 👑
  • YAS_K_F — 0x46, F 👑
  • YAS_K_G — 0x47, G 👑
  • YAS_K_H — 0x48, H 👑
  • YAS_K_I — 0x49, I 👑
  • YAS_K_J — 0x4a, J 👑
  • YAS_K_K — 0x4b, K 👑
  • YAS_K_L — 0x4c, L 👑
  • YAS_K_M — 0x4d, M 👑
  • YAS_K_N — 0x4e, N 👑
  • YAS_K_O — 0x4f, O 👑
  • YAS_K_P — 0x50, P 👑
  • YAS_K_Q — 0x51, Q 👑
  • YAS_K_R — 0x52, R 👑
  • YAS_K_S — 0x53, S 👑
  • YAS_K_T — 0x54, T 👑
  • YAS_K_U — 0x55, U 👑
  • YAS_K_V — 0x56, V 👑
  • YAS_K_W — 0x57, W 👑
  • YAS_K_X — 0x58, X 👑
  • YAS_K_Y — 0x59, Y 👑
  • YAS_K_Z — 0x5a — Z 💜
  • YAS_K_OSQ — 0x5b — OpenSquareBracket
  • YAS_K_BSLASH — 0x5c — Backslash
  • YAS_K_CSQ — 0x5d — CloseSquareBracket
  • YAS_K_CARRET — 0x5e — ^
  • YAS_K_USCORE — 0x5f — Underscore
  • YAS_K_BTICK — 0x60 — Backtick
  • YAS_K_a — 0x61 — a
  • YAS_K_b — 0x62 — b
  • YAS_K_c — 0x63 — c
  • YAS_K_d — 0x64 — d
  • YAS_K_e — 0x65 — e
  • YAS_K_f — 0x66 — f
  • YAS_K_g — 0x67 — g
  • YAS_K_h — 0x68 — h
  • YAS_K_i — 0x69 — i
  • YAS_K_j — 0x6a — j
  • YAS_K_k — 0x6b — k
  • YAS_K_l — 0x6c — l
  • YAS_K_m — 0x6d — m
  • YAS_K_n — 0x6e — n
  • YAS_K_o — 0x6f — o
  • YAS_K_p — 0x70 — p
  • YAS_K_q — 0x71 — q
  • YAS_K_r — 0x72 — r
  • YAS_K_s — 0x73 — s
  • YAS_K_t — 0x74 — t
  • YAS_K_u — 0x75 — u
  • YAS_K_v — 0x76 — v
  • YAS_K_w — 0x77 — w
  • YAS_K_x — 0x78 — x
  • YAS_K_y — 0x79 — y
  • YAS_K_z — 0x7a — z
  • YAS_K_OCUR — 0x7b — {
  • YAS_K_PIPE — 0x7c — Pipe
  • YAS_K_CCUR — 0x7d — }
  • YAS_K_TLD — 0x7e — Tilde
  • YAS_K_C_8 — 0x7f — Backspace; see below; depends on terminal see YAS-K-C-H
  • YAS_K_BSP — 0x7f — Backspace; see below; depends on terminal see YAS-K-C-H

okay bestie, we literally just did the whole lowercase alphabet 💅 like every single letter a through z got its own little glow-up with a name that is just… the letter. no cap, YAS_K_a is a. iconic. no notes. 🎀

and yes, <pink>YAS_K_C_8 and <pink>YAS_K_BSP are both sitting on 0x7f — same byte, two names, and the description is doing the most: <yellow>Backspace; see below; depends on terminal see YAS-K-C-H. that "see below" is not me being vague, that's genuinely what it says, so hold that thought because the explanation is further down the page. iykyk. 🙈

  • Extended keys, parsed from ANSI sequences ✨

and those? oh bestie, those are a whole other vibe, and they're coming right up… 🌈

okay so this is the part where we get into the actual key codes, and bestie there are so many of them 💖 every function key comes in four flavors — plain, Shift, Ctrl, and Alt — and each one gets its own special number. Keep these handy, you're gonna be matching them in your event loop like:

  • YAS_K_F1 — 0xf0001 — the F1 key 🎀
  • YAS_K_F2 — 0xf0002 — F2
  • YAS_K_F3 — 0xf0003 — F3
  • YAS_K_F4 — 0xf0004 — F4
  • YAS_K_F5 — 0xf0005 — F5
  • YAS_K_F6 — 0xf0006 — F6
  • YAS_K_F7 — 0xf0007 — F7
  • YAS_K_F8 — 0xf0008 — F8
  • YAS_K_F9 — 0xf0009 — F9
  • YAS_K_F10 — 0xf000a — F10
  • YAS_K_F11 — 0xf000b — F11
  • YAS_K_F12 — 0xf000c — F12

and now the Shift era begins ✨ same keys, new attitude:

  • YAS_K_S_F1 — 0xf000d — Shift-F1
  • YAS_K_S_F2 — 0xf000e — Shift-F2
  • YAS_K_S_F3 — 0xf000f — Shift-F3
  • YAS_K_S_F4 — 0xf0010 — Shift-F4
  • YAS_K_S_F5 — 0xf0011 — Shift-F5
  • YAS_K_S_F6 — 0xf0012 — Shift-F6
  • YAS_K_S_F7 — 0xf0013 — Shift-F7
  • YAS_K_S_F8 — 0xf0014 — Shift-F8
  • YAS_K_S_F9 — 0xf0015 — Shift-F9
  • YAS_K_S_F10 — 0xf0016 — Shift-F10
  • YAS_K_S_F11 — 0xf0017 — Shift-F11
  • YAS_K_S_F12 — 0xf0018 — Shift-F12

Ctrl girlies, this one's for you 💜:

  • YAS_K_C_F1 — 0xf0019 — Ctrl-F1
  • YAS_K_C_F2 — 0xf001a — Ctrl-F2
  • YAS_K_C_F3 — 0xf001b — Ctrl-F3
  • YAS_K_C_F4 — 0xf001c — Ctrl-F4
  • YAS_K_C_F5 — 0xf001d — Ctrl-F5
  • YAS_K_C_F6 — 0xf001e — Ctrl-F6
  • YAS_K_C_F7 — 0xf001f — Ctrl-F7
  • YAS_K_C_F8 — 0xf0020 — Ctrl-F8
  • YAS_K_C_F9 — 0xf0021 — Ctrl-F9
  • YAS_K_C_F10 — 0xf0022 — Ctrl-F10
  • YAS_K_C_F11 — 0xf0023 — Ctrl-F11
  • YAS_K_C_F12 — 0xf0024 — Ctrl-F12

and closing out the set, Alt nation 🌸 the numbers literally just keep climbing, no skips, no gaps, it's giving organized:

  • YAS_K_A_F1 — 0xf0025 — Alt-F1
  • YAS_K_A_F2 — 0xf0026 — Alt-F2
  • YAS_K_A_F3 — 0xf0027 — Alt-F3
  • YAS_K_A_F4 — 0xf0028 — Alt-F4
  • YAS_K_A_F5 — 0xf0029 — Alt-F5
  • YAS_K_A_F6 — 0xf002a — Alt-F6
  • YAS_K_A_F7 — 0xf002b — Alt-F7
  • YAS_K_A_F8 — 0xf002c — Alt-F8
  • YAS_K_A_F9 — 0xf002d — Alt-F9
  • YAS_K_A_F10 — 0xf002e — Alt-F10
  • YAS_K_A_F11 — 0xf002f — Alt-F11
  • YAS_K_A_F12 — 0xf0030 — Alt-F12

so that's 0xf0001 all the way up to 0xf0030, twelve keys times four modifiers, a whole lil family tree of function key constants 🫶 ngl the fact that the values are sequential and hex is such a slay — you can literally do math on them if you're feeling spicy. 💅

okay the keycode list just keeps going and honestly? iconic of it 💅 so here's the rest of the arrow-key-adjacent squad:

  • YAS_K_LEFT — 0xf0031 — Left
  • YAS_K_UP — 0xf0032 — Up
  • YAS_K_DOWN — 0xf0033 — Down
  • YAS_K_RIGHT — 0xf0034 — Right
  • YAS_K_HOME — 0xf0035 — Home
  • YAS_K_END — 0xf0036 — End
  • YAS_K_PGUP — 0xf0037 — PageUp
  • YAS_K_PGDN — 0xf0038 — PageDown
  • YAS_K_INS — 0xf0039 — Insert
  • YAS_K_DEL — 0xf003a — Delete
  • YAS_K_C_LEFT — 0xf003b — Ctrl-Left
  • YAS_K_C_UP — 0xf003c — Ctrl-Up
  • YAS_K_C_DOWN — 0xf003d — Ctrl-Down
  • YAS_K_C_RIGHT — 0xf003e — Ctrl-Right
  • YAS_K_S_LEFT — 0xf003f — Shift-Left
  • YAS_K_S_UP — 0xf0040 — Shift-Up
  • YAS_K_S_DOWN — 0xf0041 — Shift-Down
  • YAS_K_S_RIGHT — 0xf0042 — Shift-Right
  • YAS_K_A_LEFT — 0xf0043 — Alt-Left
  • YAS_K_A_UP — 0xf0044 — Alt-Up
  • YAS_K_A_DOWN — 0xf0045 — Alt-Down
  • YAS_K_A_RIGHT — 0xf0046 — Alt-Right
  • YAS_K_S_TAB — 0xf0047 — Shift-Tab (Backtab)
  • YAS_K_C_HOME — 0xf0048 — Ctrl-Home
  • YAS_K_C_END — 0xf0049 — Ctrl-End
  • YAS_K_C_INS — 0xf004a — Ctrl-Insert
  • YAS_K_C_DEL — 0xf004b — Ctrl-Delete
  • YAS_K_C_PGUP — 0xf004c — Ctrl-PageUp
  • YAS_K_C_PGDN — 0xf004d — Ctrl-PageDown
  • YAS_K_S_HOME — 0xf004e — Shift-Home
  • YAS_K_S_END — 0xf004f — Shift-End
  • YAS_K_S_INS — 0xf0050 — Shift-Insert
  • YAS_K_S_DEL — 0xf0051 — Shift-Delete
  • YAS_K_S_PGUP — 0xf0052 — Shift-PageUp
  • YAS_K_S_PGDN — 0xf0053 — Shift-PageDown
  • YAS_K_A_HOME — 0xf0054 — Alt-Home
  • YAS_K_A_END — 0xf0055 — Alt-End
  • YAS_K_A_INS — 0xf0056 — Alt-Insert
  • YAS_K_A_DEL — 0xf0057 — Alt-Delete
  • YAS_K_A_PGUP — 0xf0058 — Alt-PageUp
  • YAS_K_A_PGDN — 0xf0059 — Alt-PageDown
  • YAS_K_KP5 — 0xf005a — Keypad 5 with NumLock off

okay and then there's this whole other lil corner of the keyboard that doesn't even have "normal" keys, bestie 😭

F13-F20 — those get sent by the Linux console and by some other terminals when you hit Shift-F1 through Shift-F8 — they get reported as YAS_K_S_F1 all the way up to YAS_K_S_F8. so like, Shift-F1 = YAS_K_S_F1, Shift-F8 = YAS_K_S_F8, you get the vibe ✨

  • Alt-<letter>

and these codes? they're not hardcoded one by one, nope — they get generated by a helper macro: YAS_K_ALT(keycode) 🫶 so you feed it the keycode and it does the thing for you. slay.

Okay so continuing the key list, no interruptions, we're locked in 💅 Every one of these is an Alt-something constant, and here's the whole lineup:

  • YAS_K_A_BT — Alt-Backtick
  • YAS_K_A_1 — Alt-1
  • YAS_K_A_2 — Alt-2
  • YAS_K_A_3 — Alt-3
  • YAS_K_A_4 — Alt-4
  • YAS_K_A_5 — Alt-5
  • YAS_K_A_6 — Alt-6
  • YAS_K_A_7 — Alt-7
  • YAS_K_A_8 — Alt-8
  • YAS_K_A_9 — Alt-9
  • YAS_K_A_0 — Alt-0
  • YAS_K_A_MINUS — Alt-Minus
  • YAS_K_A_EQ — Alt-=
  • YAS_K_A_BSP — Alt-Backspace
  • YAS_K_A_C_H — Alt-Backspace, but specifically on terminals where Backspace sends ^H 🫠
  • YAS_K_A_TAB — Alt-Tab (if not used by the window manager)
  • YAS_K_A_RET — Alt-Enter
  • YAS_K_A_SPACE — Alt-Space
  • YAS_K_A_TLD — Alt-Tilde
  • YAS_K_A_EXCL — Alt-!
  • YAS_K_A_AT — Alt-@
  • YAS_K_A_HASH — Alt-#
  • YAS_K_A_POUND — Alt-$
  • YAS_K_A_PERC — Alt-%
  • YAS_K_A_CARRET — Alt-^
  • YAS_K_A_AND — Alt-Ampersand
  • YAS_K_A_STAR — Alt-Star
  • YAS_K_A_OBRA — Alt-(
  • YAS_K_A_CBRA — Alt-)
  • YAS_K_A_UND — Alt-_
  • YAS_K_A_PLUS — Alt-+
  • YAS_K_A_a — Alt-a
  • YAS_K_A_b — Alt-b
  • YAS_K_A_c — Alt-c
  • YAS_K_A_d — Alt-d
  • YAS_K_A_e — Alt-e
  • YAS_K_A_f — Alt-f
  • YAS_K_A_g — Alt-g
  • YAS_K_A_h — Alt-h
  • YAS_K_A_i — Alt-i
  • YAS_K_A_j — Alt-j
  • YAS_K_A_k — Alt-k
  • YAS_K_A_l — Alt-l
  • YAS_K_A_m — Alt-m
  • YAS_K_A_n — Alt-n
  • YAS_K_A_o — Alt-o
  • YAS_K_A_p — Alt-p
  • YAS_K_A_q — Alt-q
  • YAS_K_A_r — Alt-r
  • YAS_K_A_s — Alt-s
  • YAS_K_A_t — Alt-t
  • YAS_K_A_u — Alt-u
  • YAS_K_A_v — Alt-v
  • YAS_K_A_w — Alt-w
  • YAS_K_A_x — Alt-x

Like, the naming is lowkey so consistent it's basically a pattern bestie — YAS_K_A_ and then the thing, and the thing is just the character. Once you clock the vibe you can guess the rest, no cap. 🌸

  • YAS_K_A_y — Alt-y
  • YAS_K_A_z — Alt-z
  • YAS_K_A_A — Alt-Shift-a
  • YAS_K_A_B — Alt-Shift-b
  • YAS_K_A_C — Alt-Shift-c
  • YAS_K_A_D — Alt-Shift-d
  • YAS_K_A_E — Alt-Shift-e
  • YAS_K_A_F — Alt-Shift-f
  • YAS_K_A_G — Alt-Shift-g
  • YAS_K_A_H — Alt-Shift-h
  • YAS_K_A_I — Alt-Shift-i
  • YAS_K_A_J — Alt-Shift-j
  • YAS_K_A_K — Alt-Shift-k
  • YAS_K_A_L — Alt-Shift-l
  • YAS_K_A_M — Alt-Shift-m
  • YAS_K_A_N — Alt-Shift-n
  • YAS_K_A_O — Alt-Shift-o; defined for completeness but cannot be received, because \eO is a key sequence prefix
  • YAS_K_A_P — Alt-Shift-p
  • YAS_K_A_Q — Alt-Shift-q
  • YAS_K_A_R — Alt-Shift-r
  • YAS_K_A_S — Alt-Shift-s
  • YAS_K_A_T — Alt-Shift-t
  • YAS_K_A_U — Alt-Shift-u
  • YAS_K_A_V — Alt-Shift-v
  • YAS_K_A_W — Alt-Shift-w
  • YAS_K_A_X — Alt-Shift-x
  • YAS_K_A_Y — Alt-Shift-y
  • YAS_K_A_Z — Alt-Shift-z

✨ Functions ✨

okay so every single function in the API works with a pointer to an opaque yascreen structure. that structure is allocated internally in the library by yascreen_init, and it is literally the job of your user program to keep track of it. also: the library is thread safe, as long as each struct yascreen object is only ever accessed by a single thread. periodt 💅

yascreen_init

inline yascreen *yascreen_init(int sx,int sy);

allocates and initializes screen data 🎀

output defaults to stdout

if the output is a terminal and the initial size is (0,0), the screen size gets autodetected. if autodetection fails or returns 0x0, it defaults to 80x24

in case of error, returns NULL 😭

yascreen_ver

inline const char *yascreen_ver(void);

returns a string with the library version ✨

yascreen_setout

inline int yascreen_setout(yascreen *s,ssize_t (*out)(yascreen *s,const void *data,size_t len));

sets the callback that handles output 🫶

if out=NULL, the output goes to stdout

the callback may implement internal buffering; a flush is signalled by calling out with len=0

yascreen_set_unicode

inline void yascreen_set_unicode(yascreen *s,int on);

enables unicode input processing (on is non-zero) or disables it (on=0) 🌈

by default, unicode mode is on

changing the unicode input processing will flush all pending input 💀

yascreen_set_telnet

inline void yascreen_set_telnet(yascreen *s,int on);

enables telnet sequence processing (on is non-zero) or disables it (on=0) 🌸

by default, telnet mode is off

yascreen_init_telnet

inline void yascreen_init_telnet(yascreen *s);

depending on telnet sequence processing, sends a set of telnet initialization sequences 🧚

yascreen_resize

inline int yascreen_resize(yascreen *s,int sx,int sy);

resizes the screen 🦋

you should redraw afterwards

since allocation is involved, this may fail and return -1

yascreen_free

inline void yascreen_free(yascreen *s);

finishes the lifecycle of struct yascreen — all internally allocated memory is freed 💖

yascreen_term_save

inline void yascreen_term_save(yascreen *s);

saves the current terminal state on top of the state stack 💅

yascreen_term_restore

inline void yascreen_term_restore(yascreen *s);

restores the previously saved terminal state from the top of the state stack ✨

yascreen_term_push

inline void yascreen_term_push(yascreen *s);

pushes the current terminal state to the state stack 🎀

yascreen_term_pop

inline void yascreen_term_pop(yascreen *s);

pops and restores the previously saved terminal state from the state stack 🫶

yascreen_term_set

inline void yascreen_term_set(yascreen *s,int mode);

sets the terminal for proper screen operation 🌟

mode is a bitmask, containing one of:

  • YAS_NOBUFF (1) — turn off canonical mode (disable ICANON and IEXTEN)
  • YAS_NOSIGN (2) — disable ISIG
  • YAS_NOECHO (4) — disable local echo (ECHO)
  • YAS_ONLCR (8) — ONLCR or OPOST

yascreen_printxy

inline int yascreen_printxy(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));

prints at position; if data exceeds the buffer, then it gets truncated ✂️

yascreen_putsxy

inline int yascreen_putsxy(yascreen *s,int x,int y,uint32_t attr,const char *str);

prints at position; if data exceeds the buffer, then it gets truncated ✂️

yascreen_printxyu

inline int yascreen_printxyu(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));

prints at position; if data exceeds the buffer, then it gets truncated ✂️

the screen is immediately updated 🔥

yascreen_putsxyu

inline int yascreen_putsxyu(yascreen *s,int x,int y,uint32_t attr,const char *str);

prints at position; if data exceeds the buffer, then it gets truncated ✂️

the screen is immediately updated 🔥

yascreen_update

inline int yascreen_update(yascreen *s);

syncs memory state to the screen 🖥️

since allocation is involved, this may fail and return -1

yascreen_redraw

inline void yascreen_redraw(yascreen *s);

sets the next update to be a full redraw 🔄

yascreen_clear_mem

inline void yascreen_clear_mem(yascreen *s,uint32_t attr);

clears the memory buffer 🧼

all cells in the screen are set to Space, using attr for colors and style 🎨

yascreen_cursor

inline void yascreen_cursor(yascreen *s,int on);

hides the cursor (on=0) or shows it (on is non-zero) 👀

the screen is updated immediately ⚡

yascreen_cursor_xy

inline void yascreen_cursor_xy(yascreen *s,int x,int y);

bestie, this one moves the cursor to a position 💅

the screen gets updated immediately, no waiting around

yascreen_altbuf

inline void yascreen_altbuf(yascreen *s,int on);

flips between the regular buffer and the alternative buffer 🌈

screen updates immediately again, she does not do queues

yascreen_clear

inline void yascreen_clear(yascreen *s);

clears the real screen, and literally zero change to the memory buffers 🧹

yascreen_clearln

inline void yascreen_clearln(yascreen *s);

clears just the current line, and again, no change to memory buffers ✨

yascreen_update_attr

inline void yascreen_update_attr(yascreen *s,uint32_t oattr,uint32_t nattr);

applies the difference between two attrs and outputs the optimized ANSI sequence to switch from oattr to nattr 🔥

if oattr=0xffffffff, the full ANSI sequence gets generated

no change to memory buffers, okay? none.

yascreen_set_attr

yascreen_set_attr(s,attr)

resets all attrs and sets one specific attr (attr) 👑

yascreen_print

inline int yascreen_print(yascreen *s,const char *format,...) __attribute__((format(printf,2,3)));

yascreen_write

inline int yascreen_write(yascreen *s,const char *str,int len);

yascreen_puts

inline int yascreen_puts(yascreen *s,const char *str);

yascreen_clearln_s

inline const char *yascreen_clearln_s(yascreen *s);

prints in line mode 🎀

yascreen_sx

inline int yascreen_sx(yascreen *s);

gets the current x size 📏

yascreen_sy

inline int yascreen_sy(yascreen *s);

gets the current y size 📏

yascreen_x

inline int yas<|place_holder_mm_span_0442|>in int yascreen_x(yascreen *s);

wait no, that's not it, let me not be chaotic 😭 it's exactly this:

inline int yascreen_x(yascreen *s);

gets the current x 📍

yascreen_y

inline int yascreen_y(yascreen *s);

gets the current y 📍

yascreen_esc_to

inline void yascreen_esc_to(yascreen *s,int timeout);

sets the timeout for a single ESC key press ⏳

yascreen_ckto

inline void yascreen_ckto(yascreen *s);

if you're running an external event loop, this call checks for a single ESC key 👀

it should be called regularly enough that the timeout we specified above doesn't get extended too much

if it's not called often enough, then a single ESC gets yielded after a longer timeout 😬

if it's not called at all, then a single ESC gets yielded with the next key press

yascreen_willto

inline uint64_t yascreen_willto(yascreen *s);

a single ESC key plus a timeout after it is quite the rare event, fr fr

so help your application optimize its event loop by not constantly polling yascreen_ckto 🫶

yascreen_willto tells you if there's a pending timeout, and when

returns 0 if there is no pending timeout, otherwise the remaining time in milliseconds ⏱️

yascreen_getch_to

inline int yascreen_getch_to(yascreen *s,int timeout);

waits for a key, returns ASCII or extended keycode, and waits no more than timeout in milliseconds ⌨️

yascreen_getch

yascreen_getch(s)

gets a key with no timeout, periodt

this macro expands to yascreen_getch_to(s,0)

zero timeout = wait forever 😌

yascreen_getch_nowait

yascreen_getch_nowait(s)

gets a key, if there's one available, and returns immediately ⚡

this macro expands to yascreen_getch_to(s,-1)

negative timeout = do not wait

yascreen_ungetch

inline void yascreen_ungetch(yascreen *s,int key);

puts a key value back into the key buffer ↩️

the internal key buffer is dynamically allocated, so there's literally no limit on how many key codes you can put back 💖 but if memory allocation fails, the error will not be reported and the key will not be put into the buffer

yascreen_pushch

inline void yascreen_pushch(yascreen *s,int key);

pushes a key value at the end of the key buffer ➡️

similar to yascreen_ungetch, but the key code gets returned after all the other key codes currently in the buffer

the internal key buffer is dynamically allocated, so again, no limit on how many key codes may be put back 💖 but if memory allocation fails, the error will not be reported and the key will not be put into the buffer

yascreen_feed

inline void yascreen_feed(yascreen *s,unsigned char c);

feeds the key sequence state machine with a byte stream 🌊

this is useful for implementing an external event loop and reading key codes with yascreen_getch_nowait until it returns YAS_K_NONE

yascreen_peekch

inline int yascreen_peekch(yascreen *s);

peeks for a key without removing it from the input queue 👀✨

yascreen_getsize

inline void yascreen_getsize(yascreen *s,int *sx,int *sy);

gets the last reported screen size 📐

sets both to 0 if there isn't one

this yields a valid result after YAS_SCREEN_SIZE is returned as a keypress

yascreen_reqsize

inline void yascreen_reqsize(yascreen *s);

asks the terminal to report its size via an ANSI sequence 🙋‍♀️

yascreen_set_hint_i

inline void yascreen_set_hint_i(yascreen *s,int hint);

yascreen_get_hint_i

inline int yascreen_get_hint_i(yascreen *s);

yascreen_set_hint_p

inline void yascreen_set_hint_p(yascreen *s,void *hint);

yascreen_get_hint_p

inline void *yascreen_get_hint_p(yascreen *s);

get/set opaque hint values 🎁

integer and pointer hints are stored separately and both can be used at the same time

these are useful to link the yascreen instance to user program data

for example, a single output callback may output to a socket or a terminal, depending on the hint values 💅

yascreen_line_flush

inline void yascreen_line_flush(yascreen *s,int on);

enables/disables auto flush for line and direct screen oriented operations 🚰

yascreen versions before 1.77 didn't use buffered output and would immediately send the output to the screen

disabling internal flush can help an application optimize the number of write calls, at the cost of performing an explicit flush after each group of operations

explicit flush example:

yascreen_write(s,"",0);

yascreen_getwch_to

inline wchar_t yascreen_getwch_to(yascreen *s,int timeout);

waits for a key, returns a wide character or extended keycode, and waits no more than timeout in milliseconds 🌸

yascreen_getwch_to does not work in non-unicode mode and will always return YAS_K_NONE 💀

mixing the utf8 and wide character input modes will break on multibyte utf8 sequences and is not supported 🚫

yascreen_getwch

yascreen_getwch(s)

gets a key as a wide character, no timeout 😌

this macro expands to yascreen_getwch_to(s,0)

zero timeout = wait forever

yascreen_getwch does not work in non-unicode mode and will always return YAS_K_NONE 💀

yascreen_getwch_nowait

yascreen_getwch_nowait(s)

gets a key as a wide character, if there's one available, and returns immediately ⚡

this macro expands to yascreen_getwch_to(s,-1)

negative timeout = do not wait

yascreen_getwch_nowait does not work in non-unicode mode and will always return YAS_K_NONE 💀

yascreen_ungetwch

inline void yascreen_ungetwch(yascreen *s,wchar_t key);

puts a wide character key value back into the key buffer ↩️

the internal key buffer is dynamically allocated, so no limit on how many key codes may be put back 💖 but if memory allocation fails, the error will not be reported and the key will not be put into the buffer

the internal key buffer contains utf8, and the wide character will be expanded to the appropriate utf8 sequence 🦋

yascreen_ungetwch does not do anything in non-unicode mode 🙈

yascreen_peekwch

inline wchar_t yascreen_peekwch(yascreen *s);

peeks for a key without removing it from the input queue 👀

yascreen_peekwch does not work in non-unicode mode and will always return YAS_K_NONE 💀

okay bestie that's the whole page, we did it 🎉 every single function, no skips, no cap. this page is from yascreen, dated July 29, 2026, and lives at YASCREEN(3) — go forth and slay your terminal UI 💅✨👑

📦 where this page comes from