1FbTerm(1)                     FbTerm User Manual                     FbTerm(1)
2
3
4

NAME

6       FbTerm - a fast Frame Buffer based TERMinal emulator for linux
7

SYNOPSIS

9       fbterm [options] [--] [command [arguments]]
10

DESCRIPTION

12       FbTerm  is  a fast terminal emulator for linux with frame buffer device
13       or VESA video card. Features include:
14
15         * mostly as fast  as  terminal  of  linux  kernel  while  accelerated
16       scrolling is enabled
17         *  select  font with fontconfig and draw text with freetype2, same as
18       Qt/Gtk+ based GUI apps
19         * dynamically create/destroy  up  to  10  windows  initially  running
20       default shell
21         * record scroll-back history for every window
22         *  auto-detect current locale and convert text encoding, support dou‐
23       ble width scripts like Chinese, Japanese etc
24         * switch between configurable additional text encodings with hot keys
25       on the fly
26         *  copy/past selected text between windows with mouse when gpm server
27       is running
28         * change the orientation of screen display, a.k.a. screen rotation
29         * lightweight input method framework with client-server architecture
30         * background image for eye candy
31

OPTIONS

33       command [arguments] may be given to override  the  built-in  choice  of
34       shell  program.  Normally  FbTerm checks the SHELL variable. If that is
35       not set, it tries to use the user's login shell  program  specified  in
36       the password file. If that is not set, /bin/sh will be used. You should
37       use the -- argument to separate FbTerm's  options  from  the  arguments
38       supplied to the command.
39
40       FbTerm  first  uses  option  value specified in command line arguments,
41       then in the configure  file  $HOME/.fbtermrc.   If  that  file  doesn't
42       exist, FbTerm will create it with default options on startup.
43
44       -h, --help
45              display the help and exit
46
47       -V, --version
48              display FbTerm version and exit
49
50       -v, --verbose
51              display extra FbTerm's information
52
53       -n, --font-names=text
54              specify font family names
55
56       -s, --font-size=num
57              specify font pixel size
58
59       --font-width=num
60              force font width
61
62       --font-height=num
63              force font height
64
65       -f, --color-foreground=num
66              specify foreground color
67
68       -b, --color-background=num
69              specify background color
70
71       -e, --text-encodings=text
72              specify additional text encodings
73
74       -a, --ambiguous-wide
75              treat ambiguous width characters as wide
76
77       -r, --screen-rotate=num
78              specify the orientation of screen display
79
80       -i, --input-method=text
81              specify input method program
82
83       --cursor-shape=num
84              specify default cursor shape
85
86       --cursor-interval=num
87              specify cursor flash interval
88
89       --vesa-mode=num
90              specify VESA video mode
91
92       --vesa-mode=list
93              display available VESA video modes
94
95
96       see comments in $HOME/.fbtermrc for details of these options.
97

SHORTCUT SUMMARY

99       keyboard:
100         CTRL_ALT_E:    exit from FbTerm
101         CTRL_ALT_C:    create a new window
102         CTRL_ALT_D:    destroy current window
103         CTRL_ALT_1:    switch to window 1
104         CTRL_ALT_2:    switch to window 2
105         CTRL_ALT_3:    switch to window 3
106         CTRL_ALT_4:    switch to window 4
107         CTRL_ALT_5:    switch to window 5
108         CTRL_ALT_6:    switch to window 6
109         CTRL_ALT_7:    switch to window 7
110         CTRL_ALT_8:    switch to window 8
111         CTRL_ALT_9:    switch to window 9
112         CTRL_ALT_0:    switch to window 10
113         SHIFT_LEFT:    switch to previous window
114         SHIFT_RIGHT:   switch to next window
115         SHIFT_PAGEUP:    history scroll up
116         SHIFT_PAGEDOWN:  history scroll down
117         CTRL_ALT_F1:                 switch to encoding of current locale
118         CTRL_ALT_F2 to CTRL_ALT_F6:  switch to additional encodings
119         CTRL_SPACE:    toggle input method
120         CTRL_ALT_K:    kill input method server
121
122       mouse:
123         move when left button down:      select text
124         double click with left button:   auto select text
125         click with right button:         paste selected text
126
127       Sometimes  above  actions  will  not work, please try to redo them with
128       shift key holding down.
129

FRAME BUFFER DEVICE

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

VESA VIDEO DEVICE

137       From  version  1.6,  FbTerm  adds  VESA video card support. By default,
138       FbTerm tries frame buffer device first, if failure, then tries  to  use
139       VESA device with highest resolution and color depth. option "vesa-mode"
140       may be given to force only open VESA device with  the  specified  video
141       mode.  To see available video modes for your VESA card, execute "fbterm
142       --vesa-mode=list".
143
144       Attention: 1) VESA support requires root privilege to work; 2)  do  not
145       force  to  use  VESA  device  on  the  system  with frame buffer device
146       enabled, they maybe conflict with each other.
147

FONT

149       FbTerm invokes fontconfig to get a font list, if the first font doesn't
150       contain the glyph for the rendering character, it will try second font,
151       then the third, ... and so on, user can see this ordered font list with
152       "fbterm -v".
153
154       If  you  don't  like the fonts selected by FbTerm, execute "fc-list" to
155       get available fonts, choose favorites as the  value  of  option  "font-
156       names".  You  may  also  modify the configure file of fontconfig, which
157       will change the behavior of all programs based on fontconfig!
158

TEXT ENCODING

160       By using iconv, FbTerm converts other encodings  to  internal  encoding
161       UTF-8.  On  startup,  FbTerm  checks variable LC_CTYPE to determine the
162       default text encoding, which is binded to shortcut  CTRL_ALT_F1.   User
163       can  specify up to 5 additional encodings with option "text-encodings",
164       for example, as a  Chinese  user,  you  set  "text-encodings=gbk,big5",
165       shortcut CTRL_ALT_F2 will bind to gbk, and CTRL_ALT_F3 bind to big5.
166
167       In a number of CJK encodings there are ambiguous width characters which
168       have a width of either narrow or wide depending on the context of their
169       use.  By default, FbTerm treats them as narrow width characters, option
170       "ambiguous-wide" may be used to change the behavior.
171

BACKGROUND IMAGE

173       FbTerm doesn't load and parse  any  image  file  with  various  formats
174       directly,  instead  it  takes  a  screen shot of frame buffer device on
175       startup if variable FBTERM_BACKGROUND_IMAGE is defined, then uses  this
176       screen  shot  as  the background for text rendering. In order to enable
177       background image support, user should first put a image to frame buffer
178       device with a image viewer. A wrapper script using fbv is listed below:
179
180           #!/bin/bash
181
182           #  fbterm-bi:  a  wrapper  script  to  enable background image with
183       fbterm
184           # usage: fbterm-bi /path/to/image fbterm-options
185
186           echo -ne "\e[?25l" # hide cursor
187
188           fbv -ciuker "$1" << EOF
189           q
190           EOF
191
192           shift
193           export FBTERM_BACKGROUND_IMAGE=1
194           exec fbterm "$@"
195
196       Attention: 1) do not enable background image  on  frame  buffer  device
197       with  8bpp  depth,  because  FbTerm changes color map table for correct
198       text rendering; 2) if the screen shot is different  from  the  original
199       image, try to use a fast scrolling disabled frame buffer device.
200

256 COLOR EXTENSION

202       FbTerm  supports  xterm's 256 color mode extension. The first 16 colors
203       are the default terminal colors. Additionally, there's  a  6x6x6  color
204       cube,  and  24  grayscale tones. But xterm's 256 color escape sequences
205       conflict with the linux sequences implemented  by  FbTerm,  so  private
206       escape sequences were introduced to support this feature:
207
208           ESC [ 1 ; n }                   set foreground color to n (0 - 255)
209           ESC [ 2 ; n }                   set background color to n (0 - 255)
210           ESC  [  3 ; n ; r ; g ; b }       set color n to (r, g, b) ,  n, r,
211       g, b all in (0 - 255)
212
213       A new terminfo database entry named "fbterm" was  added  to  use  these
214       private  sequences,  all program based on terminfo should work with it.
215       By default, FbTerm sets environment variable "TERM" to  value  "linux",
216       user need run "TERM=fbterm /path/to/program" to enable 256 color mode.
217

INPUT METHOD

219       Instead  of  adding  input  method  directly in FbTerm, a client-server
220       based input method framework is designed to do this work.  FbTerm  acts
221       as  a  client, standalone IM program as a server, and they run in sepa‐
222       rated processes.
223
224       As a normal IM user, you  should  install  a  IM  program  written  for
225       FbTerm,   and  specify  it  as  the  value  of  option  "input-method".
226       CTRL_SPACE is the shortcut to  activate/deactivate  input  method.  And
227       CTRL_ALT_K may be used to kill the IM program when it has freezed.
228
229

SECURITY NOTES

231       FbTerm  tries  to change linux kernel key map table to setup shortcuts,
232       which requires SYS_TTY_CONFIG capability since kernel  version  2.6.15.
233       It means FbTerm should be a setuid 0 program to allow non-root users to
234       use shortcuts. FbTerm only switches to root privilege temporarily  when
235       changing  key map table, we believe it's pretty much free from security
236       problems.  If you really don't like this and have a linux  kernel  with
237       file  system  capabilities enabled, which allow user to give binaries a
238       subset of root's powers without using setuid 0 (official kernel  2.6.27
239       includes  it), you can run command "sudo setcap 'cap_sys_tty_config+ep'
240       /path/to/fbterm".
241
242       FbTerm redirects /dev/tty0 output to the  pseudo  terminal  of  current
243       sub-window. In linux before version 2.6.10, anybody can do this as long
244       as the output was not redirected yet; since version 2.6.10,  only  root
245       or a process with the CAP_SYS_ADMIN capability may do this.  You should
246       do similar work with above ones for FbTerm to enable this  feature  for
247       non-root users.
248
249

PERFORMANCE

251       According  test  result,  FbTerm  spends more than 95% time on painting
252       screen. Speedup painting will significantly increase performance.  Here
253       are some suggestions for frame buffer device:
254
255         *  Enable  fast  scrolling on frame buffer device. The visible screen
256       will be just a window of the video memory, when scrolling, FbTerm  only
257       change the start of window, no need to repaint the whole screen.
258
259         *  On  Intel  P6  family  processors  the Memory Type Range Registers
260       (MTRRs) may be used to control processor access to  memory  ranges.  If
261       you  have  video  card  on  a  PCI or AGP bus, enabling write-combining
262       allows bus write transfers to be combined into a larger transfer before
263       bursting  over  the  PCI/AGP  bus.  This  can  increase  performance of
264       FbTerm's paint operations.
265
266       Maybe you need to enable them manually for your video card.  For  exam‐
267       ple,  by default fast scrolling and write-combining are all disabled on
268       general VESA frame buffer device, GRUB/LILO configure  file  should  be
269       modified to enable them.  A GRUB example is showed below:
270
271       title Ubuntu
272           root (hd0,0)
273           kernel   /boot/vmlinuz   ro   root=LABEL=UBUNTU   splash  vga=0x317
274       video=vesafb:ywrap,mtrr:3
275           initrd /boot/initrd.img
276
277       You may check fast scrolling status with "fbterm -v",  a  message  with
278       "scrolling:   redraw"  means  fast  scrolling  is  disabled,  otherwise
279       enabled.
280

AUTHOR

282       Written by dragchan.
283

REPORTING BUGS

285       Please submit bug reports to <http://code.google.com/p/fbterm/issues>.
286
288       Copyright © 2008-2010 dragchan.  License GPLv2: GNU GPL  version  2  or
289       later <http://gnu.org/licenses/gpl.html>.
290       This  is  free  software:  you  are free to change and redistribute it.
291       There is NO WARRANTY, to the extent permitted by law.
292
293
294
295FbTerm 1.7                       October 2010                        FbTerm(1)
Impressum