fbterm

FbTerm(1)                     FbTerm User Manual                     FbTerm(1)



NAME
       FbTerm - a fast Frame Buffer based TERMinal emulator for linux

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

DESCRIPTION
       FbTerm is a fast terminal emulator for linux with frame buffer device
       or VESA video card. Features include:

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

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.

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!

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.

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.


PERFORMANCE
       According test result, FbTerm spends more than 95% time on painting
       screen. Speedup painting will significantly increase performance. Here
       are some suggestions for frame buffer device:

         * Enable fast scrolling on frame buffer device. The visible screen
       will be just a window of the video memory, when scrolling, FbTerm only
       change the start of window, no need to repaint the whole screen.

         * On Intel P6 family processors the Memory Type Range Registers
       (MTRRs) may be used to control processor access to memory ranges. If
       you have video card on a PCI or AGP bus, enabling write-combining
       allows bus write transfers to be combined into a larger transfer before
       bursting over the PCI/AGP bus. This can increase performance of
       FbTerm's paint operations.

       Maybe you need to enable them manually for your video card. For
       example, by default fast scrolling and write-combining are all disabled
       on general VESA frame buffer device, GRUB/LILO configure file should be
       modified to enable them.  A GRUB example is showed below:

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

       You may check fast scrolling status with "fbterm -v", a message with
       "scrolling: redraw" means fast scrolling is disabled, otherwise
       enabled.

AUTHOR
       Written by dragchan.

REPORTING BUGS
       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.



FbTerm 1.7                       October 2010                        FbTerm(1)