FbTerm(1)

🌸 FbTerm(1) — FbTerm User Manual 🌸

💖 NAME

FbTerm — a fast Frame Buffer based TERMinal emulator for linux ✨

---

✨ SYNOPSIS

fbterm [options] [--] [command [arguments]]

---

🦋 DESCRIPTION

okay so bestie, FbTerm is a fast terminal emulator for linux, and it runs on a frame buffer device or a VESA video card. and the feature list?? it's giving main character energy fr fr:

• mostly as fast as terminal of linux kernel while accelerated scrolling is enabled
• select font with fontconfig and draw text with freetype2, same as Qt/Gtk+ based GUI apps
• dynamically create/destroy up to 10 windows initially running default shell
• record scroll-back history for every window
• auto-detect current locale and convert text encoding, support double width scripts like Chinese, Japanese etc
• switch between configurable additional text encodings with hot keys on the fly
• copy/past selected text between windows with mouse when gpm server is running
• change the orientation of screen display, a.k.a. screen rotation
• lightweight input method framework with client-server architecture
• background image for eye candy

---

🔥 OPTIONS

command [arguments] may be given to override the built-in choice of shell program. Normally FbTerm checks the SHELL variable. If that is not set, it tries to use the user's login shell program specified in the password file. If that is not set, /bin/sh will be used. You should use the -- argument to separate FbTerm's options from the arguments supplied to the command.

FbTerm first uses option value specified in command line arguments, then in the configure file $HOME/.fbtermrc. If that file doesn't exist, FbTerm will create it with default options on startup. 💅

• -h, --help — display the help and exit
• -V, --version — display FbTerm version and exit
• -v, --verbose — display extra FbTerm's information
• -n, --font-names=text — specify font family names
• -s, --font-size=num — specify font pixel size
• --font-width=num — force font width
• --font-height=num — force font height
• -f, --color-foreground=num — specify foreground color
• -b, --color-background=num — specify background color
• -e, --text-encodings=text — specify additional text encodings
• -a, --ambiguous-wide — treat ambiguous width characters as wide
• -r, --screen-rotate=num — specify the orientation of screen display
• -i, --input-method=text — specify input method program
• --cursor-shape=num — specify default cursor shape
• --cursor-interval=num — specify cursor flash interval
• --vesa-mode=num — specify VESA video mode
• --vesa-mode=list — display available VESA video modes

see comments in $HOME/.fbtermrc for details of these options. 👑

---

⌨️ SHORTCUT SUMMARY

🎹 keyboard

• CTRL_ALT_E — exit from FbTerm
• CTRL_ALT_C — create a new window
• CTRL_ALT_D — destroy current window
• CTRL_ALT_1 — switch to window 1
• CTRL_ALT_2 — switch to window 2
• CTRL_ALT_3 — switch to window 3
• CTRL_ALT_4 — switch to window 4
• CTRL_ALT_5 — switch to window 5
• CTRL_ALT_6 — switch to window 6
• CTRL_ALT_7 — switch to window 7
• CTRL_ALT_8 — switch to window 8
• CTRL_ALT_9 — switch to window 9
• CTRL_ALT_0 — switch to window 10
• SHIFT_LEFT — switch to previous window
• SHIFT_RIGHT — switch to next window
• SHIFT_PAGEUP — history scroll up
• SHIFT_PAGEDOWN — history scroll down
• CTRL_ALT_F1 — switch to encoding of current locale
• CTRL_ALT_F2 to CTRL_ALT_F6 — switch to additional encodings
• CTRL_SPACE — toggle input method
• CTRL_ALT_K — kill input method server

🖱️ mouse

• move when left button down — select text
• double click with left button — auto select text
• click with right button — paste selected text

Sometimes above actions will not work, please try to redo them with shift key holding down. 😭 yes really, just hold shift and try again bestie

---

🌈 FRAME BUFFER DEVICE

Before executing FbTerm, make sure there is a frame buffer device in your system, and you have read/write access right with it. Normally FbTerm tries to open /dev/fb0 and /dev/fb/0, environment variable FRAMEBUFFER may be used to override this built-in behavior. 🫶

---

⭐ VESA VIDEO DEVICE

From version 1.6, FbTerm adds VESA video card support. By default, FbTerm tries frame buffer device first, if failure, then tries to use VESA device with highest resolution and color depth. option vesa-mode may be given to force only open VESA device with the specified video mode. To see available video modes for your VESA card, execute fbterm --vesa-mode=list.

Attention: 1) VESA support requires root privilege to work; 2) do not force to use VESA device on the system with frame buffer device enabled, they maybe conflict with each other. 💀 do not do it, i'm serious

---

🎀 FONT

FbTerm invokes fontconfig to get a font list, if the first font doesn't contain the glyph for the rendering character, it will try second font, then the third, ... and so on, user can see this ordered font list with fbterm -v. 👀

If you don't like the fonts selected by FbTerm, execute fc-list to get available fonts, choose favorites as the value of option font-names. You may also modify the configure file of fontconfig, which will change the behavior of all programs based on fontconfig! ⚠️ like, all of them. periodt.

---

🦋 TEXT ENCODING

By using iconv, FbTerm converts other encodings to internal encoding UTF-8. On startup, FbTerm checks variable LC_CTYPE to determine the default text encoding, which is binded to shortcut CTRL_ALT_F1. User can specify up to 5 additional encodings with option text-encodings, for example, as a Chinese user, you set text-encodings=gbk,big5, shortcut CTRL_ALT_F2 will bind to gbk, and CTRL_ALT_F3 bind to big5. ✨

In a number of CJK encodings there are ambiguous width characters which have a width of either narrow or wide depending on the context of their use. By default, FbTerm treats them as narrow width characters, option ambiguous-wide may be used to change the behavior.

---

🌸 BACKGROUND IMAGE

FbTerm doesn't load and parse any image file with various formats directly, instead it takes a screen shot of frame buffer device on startup if variable FBTERM_BACKGROUND_IMAGE is defined, then uses this screen shot as the background for text rendering. In order to enable background image support, user should first put a image to frame buffer device with a image viewer. A wrapper script using fbv is listed below:

#!/bin/bash

# fbterm-bi: a wrapper script to enable background image with fbterm
# usage: fbterm-bi /path/to/image fbterm-options

echo -ne "\e[?25l" # hide cursor

fbv -ciuker "$1" << EOF
q
EOF

shift
export FBTERM_BACKGROUND_IMAGE=1
exec fbterm "$@"

Attention: 1) do not enable background image on frame buffer device with 8bpp depth, because FbTerm changes color map table for correct text rendering; 2) if the screen shot is different from the original image, try to use a fast scrolling disabled frame buffer device. 🫣 like, the vibes will be off otherwise

---

💜 256 COLOR EXTENSION

FbTerm supports xterm's 256 color mode extension. The first 16 colors are the default terminal colors. Additionally, there's a 6x6x6 color cube, and 24 grayscale tones. But xterm's 256 color escape sequences conflict with the linux sequences implemented by FbTerm, so private escape sequences were introduced to support this feature:

ESC [ 1 ; n }                   set foreground color to n (0 - 255)
ESC [ 2 ; n }                   set background color to n (0 - 255)
ESC [ 3 ; n ; r ; g ; b }       set color n to (r, g, b) ,  n, r, g, b all in (0 - 255)

A new terminfo database entry named fbterm was added to use these private sequences, all program based on terminfo should work with it. By default, FbTerm sets environment variable TERM to value linux, user need run TERM=fbterm /path/to/program to enable 256 color mode. 🌈

---

🧚 INPUT METHOD

Instead of adding input method directly in FbTerm, a client-server based input method framework is designed to do this work. FbTerm acts as a client, standalone IM program as a server, and they run in separated processes.

As a normal IM user, you should install a IM program written for FbTerm, and specify it as the value of option input-method. CTRL_SPACE is the shortcut to activate/deactivate input method. And CTRL_ALT_K may be used to kill the IM program when it has freezed. 💅

---

👑 SECURITY NOTES

FbTerm tries to change linux kernel key map table to setup shortcuts, which requires SYS_TTY_CONFIG capability since kernel version 2.6.15. It means FbTerm should be a setuid 0 program to allow non-root users to use shortcuts. FbTerm only switches to root privilege temporarily when changing key map table, we believe it's pretty much free from security problems. If you really don't like this and have a linux kernel with file system capabilities enabled, which allow user to give binaries a subset of root's powers without using setuid 0 (official kernel 2.6.27 includes it), you can run command sudo setcap 'cap_sys_tty_config+ep' /path/to/fbterm.

FbTerm redirects /dev/tty0 output to the pseudo terminal of current sub-window. In linux before version 2.6.10, anybody can do this as long as the output was not redirected yet; since version 2.6.10, only root or a process with the CAP_SYS_ADMIN capability may do this. You should do similar work with above ones for FbTerm to enable this feature for non-root users. 🔐

okay bestie, this is the part where we make it go FAST 💨✨

---

🔥 PERFORMANCE 🔥

ngl, this is the tea: according to test results, FbTerm spends more than 95% of its time just painting the screen. like, that's basically its whole personality. so if you speed up painting, you speed up everything. here are some suggestions for your frame buffer device, bestie 👇

• Enable fast scrolling on the frame buffer device. how does it work? the visible screen is literally just a window into the video memory — so when you scroll, FbTerm only changes the start of that window. it does not have to repaint the whole screen. iconic behaviour, no notes 💅
• On Intel P6 family processors, the Memory Type Range Registers (MTRRs) may be used to control processor access to memory ranges. and if your video card is on a PCI or AGP bus, turning on write-combining lets bus write transfers get squished together into one bigger transfer before they burst out over the PCI/AGP bus. this can increase performance of FbTerm's paint operations. slay 🎀

fr fr, you might have to enable these yourself for your video card. for example: by default, fast scrolling and write-combining are all disabled on a general VESA frame buffer device, so you'll need to edit your GRUB/LILO configure file to turn them on. here's a GRUB example 🫶

title Ubuntu
    root (hd0,0)
    kernel /boot/vmlinuz ro root=LABEL=UBUNTU splash vga=0x317 video=vesafb:ywrap,mtrr:3
    initrd /boot/initrd.img

and you can vibe check your fast scrolling status with fbterm -v — if you see a message with scrolling: redraw, that means fast scrolling is disabled. anything else means it's enabled ✨

---

👑 AUTHOR 👑

Written by dragchan. (main character energy, honestly 🌟)

---

🐛 REPORTING BUGS 🐛

found a bug? don't suffer in silence, bestie 😭 please submit bug reports to <http://code.google.com/p/fbterm/issues>.

---

📜 COPYRIGHT 📜

Copyright © 2008-2010 dragchan. License GPLv2: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. (yes that's the dramatic part, we love a disclaimer 💀)

---

and that's the whole page, bestie!! 🌈 this was FbTerm 1.7, dated October 2010 — FbTerm(1), periodt 💖✨🦋

go forth and scroll fast 🎀