TTTTT W W III NN N
T W W W I N N N
T W W III N NN
Twin - a Textmode WINdow environment
TUTORIAL
updated to version 0.4.6, 26 Mar 2003
Author: Massimiliano Ghilardi
0. Index
These are the topics discussed:
0. Index
1. Concepts
2. Supported displays
2.1. Emulated terminal
3. Configuring and Compiling twin
3.1 System Requirements
4. Installing and Starting twin
5. The Twin UI (User Interface): how to use it
6. External programs
6.1. Saving diagnostic messages (logs)
6.2. Security Statement on Sockets
7. Transparent Compression
8. Attach/Detach
9. Installing X11 and VGA fonts
10. Greetings
1. Concepts
Twin creates, draws and manages windows inside a text display.
It implements in text mode the same concepts that X11 does in graphics:
a. draw on some kind of screen (tipically a computer monitor).
b. allow multiple windows to coexist on the same screen,
and draw independently on each of them.
c. talk to external programs (even on other machines) so that
the programs receive keystrokes, mouse movements, etc.
and can send back drawing commands.
There are anyway important differences, beyond the trivial one
that `twin' works in text mode and X11 servers work in graphics:
a. Each window has an associated menu. Many windows can share
the same menu, and twin always show the menu associated
to the currently focused window.
b. In `twin', window borders are part of each window, and can be
(partially) customized by the external program that draws in it.
Things that you can't tailor in this way are:
buttons position and look, scrollbars position and look,
as they are under control of twin builtin window manager
(see the example file "twinrc" to learn how to customize the
window manager look-n-feel).
c. In `twin', windows are not just plain rectangules where programs
can draw. They can contain other windows and/or `gadgets' (small
icons you can select, like the buttons you can find in many GUIs)
and they can contain lines longer that the window width and/or more
lines than the window height, letting the user scroll them.
d. Twin implements virtual screens. Each virtual screen has very big
sizes in both directions (something like 64K character cells),
and you can scroll them by holding LEFT or MIDDLE mouse buttons
and moving the mouse to one of the screen borders. Also, you can
switch to the next virtual screen by clicking on the arrows
at the top-right of its menu bar.
e. Twin has a built-in window manager,
which needs to do a slightly different work than a typical
X11 window manager: it does window focus changes, window drags
and resizes, virtual screen changes, menu activity and dispatches
keystrokes and mouse events to the focused window.
With the help of a built-in `scroller' it also implements
virtual screen scrolling and window contents scrolling
(when you drag the scrollbar or hit the scrollbar buttons).
f. Twin has a built-in terminal emulator, so you don't have to start
any program equivalent to xterm in order to run `normal' tty programs.
Anyway, an external terminal emulator `twterm' is included among
the clients distributed with twin, in case you really need it.
Note anyway that `twterm' _needs_ the built-in terminal emulator code
to be loaded into twin, and twin is capable to auto-load such code
if needed.
2. Supported displays
Twin runs perfectly on the linux console, inside itself, in a twin terminal
and on X11: it opens a window and draws in it, does _not_ run inside an
xterm or similar.
It can also run on generic text terminals (ttys) using the termcap/ncurses
driver, but it will work far from optimal: it may have problems with mouse
(only xterm and derivatives have a standard to report mouse) and keyboard
(each terminal sends different codes for special keys: F1-F12, Pause, ...)
Currently, twin is tested on:
* Linux (x86_64, i386, aarch64, arm, PowerPC, Alpha, Sparc)
* Mac OS X (must be compiled with Xcode command line tools)
* FreeBSD (x86_64, i386)
I had yet no chance to test it on other systems.
Twin will not be able to take advantage of special features of non-Linux
system consoles until someone adds to twin the necessary code for them.
Twin can write to textmode terminals in different ways:
a: on any Linux terminal: when writing to standard output, just like any
`normal' textmode program, twin can take advantage of extra features
of the Linux terminal.
This doesn't allow displaying a few special characters, but it should
not be a big problem.
b: on any termcap or ncurses compatible terminal: this is the most generic
driver, and is quite limited. Twin writes on standard output, but due to
the broad-targeted code cannot take advantage of any extra features of
the actual terminal it runs on. Yet this allows to display on such a
large variety of terminals to be actually useful.
When choosing a method to display on ttys, twin will use (a) if available,
else fallback on (b).
2.1. Emulated terminals
The built-in terminal emulator behaves as a linux console.
Implementing it on something different than a linux console
is a little hard, as it would have to translate keyboard sequences:
For example, when you hit , a linux console sends ESC [ [ 5
while xterm and derivatives send ESC [ 1 5 ~.
Having twin correctly running in an xterm also means that each time
it receives ESC [ 1 5 ~ it must translate it into ESC [ [ 5.
But what should it do when it receives ESC [ 1 alone?
Translate to ESC [ [, sent the data without translations,
or wait for more data? There's no easy answer.
3. Configuring and Compiling twin
3.1 System Requirements
To compile twin you need the following programs installed
on your system:
* a Bourne-shell or compatible (for example bash, dash, ash...)
* make (most variants are supported: GNU make, BSD make...)
* an ANSI C compiler (for example gcc or clang)
Once you have the necessary programs listed above, you can start:
If you are trying to compile on non-Linux systems, you would do better
reading the file README.porting now, for useful tips and warnings.
Type `./configure [options]' to automatically configure twin for your system.
AUTOMATIC CONFIGURATION SHOULD ALWAYS SUFFICE;
YOU SHOULD NEVER NEED TO MANUALLY CONFIGURE TWIN.
Yet, if you really know what you are doing, you can manually tweak the
autogenerated configuration with one of `make config', `make menuconfig'
(uses "dialog"), `make gconfig' (used gdialog), `./configure [OPTIONS]'
or `scripts/Configure.sh [OPTIONS]'.
See the `Configure' help file for details.
Once you have done with configuration, you are ready to compile:
just type `make'.
Watch the compilation proceed, and, if everything goes fine,
you get what follows:
- `twin_server', the main program, in the server/ subdirectory;
- various libraries (libT*), in libs/libT*/ subdirectories;
- various clients (twcat, twterm, ...) in the clients/ subdirectory.
In case you get errors during compilation and you really can't solve
the problem by your own, you can open an issue at
sending an _EXACT_ copy of what
`make' printed and also specifying your operating system (uname -a),
and I'll try to help you.
If you have a fast computer and some spare time, you could help me a little
and try to compile every source file under every possible configuration.
This is not as huge as it may seem, and it's easy to do: just type
`make Torture'.
In case you get compile errors, please report them to me,
specifying your OS name (type `uname -a'), and the compile command
that failed, including the EXACT error messages.
4. Installing and Starting twin
If you want to install twin on your system,
make sure that the `prefix' variable set by './configure' is correct,
considering that when you will type `make install'
the various parts of twin will be placed as follows:
`twin' and the other programs (twterm, etc.) will go in $prefix/bin,
modules will go in $prefix/lib/twin/modules,
libtw.so* will go in $prefix/lib.
Once twin compiled fine, to actually install it,
type the following command as root:
make install
WARNING (1):
since twin has *NOT* been extensively tested against vulnerabilities,
it will *NOT* be installed suid-root or sgid-tty by default.
In order for the terminal emulator to work, you may need to give
such privileges to twin, but remember that you do so at your own risk!
WARNING (2):
on most systems, after the installation it is necessary to run `ldconfig'
or `ldconfig ' as root before programs can find libtw.so*
shared libraries.
WARNING (3):
if you compiled some code as modules, twin will look for them only in
$prefix/lib/twin/modules so it may not find the modules until you install
them.
To make debugging easier, if you compile with $libdir set to empty value
(i.e. make libdir= ) then twin will look for modules in the current
directory. In this way `make install' is not necessary for using modules.
In any case, you cannot mix modules from a certain version
with a `twin' executable of a different version.
After twin is installed, to start it just type
twin
If you did not install twin yet, you can go to the directory where
you compiled twin, then run:
cd server/
./twin_server
If you want, you can specify the display to use
instead of letting twin autoprobe; the syntax is:
twin [--hw=[,options]] [--hw=[,options]] ...
where is one of:
xft[@]
x11[@] or X11[@]
tty[@]
twin[@]
for an explanation of the available display methods and their options,
see paragraph 8. below about `twattach' and `twdisplay': they have
exactly the same syntax as twin for the argument `--hw=[,options]'
You can also start twin in the background without display with
twin --nohw
5. The Twin UI (User Interface): how to use it
Since the user interface of twin is quite customizable, this part
cannot cover every possible setup you might create. For this reason,
what is described here is the default setup, that you get if you do NOT
start tweaking your own ~/.config/twin/twinrc file. To learn the syntax
of such file, look at the sample configuration `twinrc' distributed with twin.
When twin comes up, you will have a blue screen (or window) with a
white menu bar on the top saying "Hit PAUSE or Mouse Right Button for Menu"
To activate the menu (this is the default menu) do what the writing says:
either hit the `PAUSE' key or hold down the right mouse button and move
the mouse on one of the words of the menu bar. A menu window will appear.
Choose the line you want, then release the right button if you were holding
it, or hit the `RETURN' key otherwise.
If you feel slightly offended by reading something so trivial and obvious,
well, I feel quite stupid too writing it, but I must start from somewhere ;)
Each word in the menu just appeared is a `menuitem'. The "≡" menuitem lets
you pop up some utility windows, including a Clock, the Options window,
the Buttons window, the Display window and the About window.
The "File" menuitem lets you Quit twin, Suspend or Detach it, Execute
arbitrary shell commands and, if the builtin terminal emulator code
is loaded, open a New Terminal window.
The "Edit" menuitem is just a standard entry but it's not usable here.
The "Modules" menuitem lets you insert/remove modules from the running twin:
you can "Run Twin Term" to insert the terminal emulator module,
you can "Stop Twin Term" to kill all terminal windows and unload the module;
you can "Run Socket Server" to insert the support code for running external
programs, you can "Stop Socket Server" to remove that code and kill all
external programs.
The "Window" menuitem is common to all menus and lets you do several
operations on windows (explained immediately below)
Ok, enough boring stuff for now... let's jump to something else.
Each window has its own menu, so opening a new window will give you
a new menu while the previous gets inaccessible. When you start without
windows, you are presented the default menu described above.
Anyway, all menus share a common part: the "Window" menuitem, which
lets you do basic operations with all windows --
Move, Resize, Scroll, Center, Maximize, UnFocus, cycle through windows
(Next), and also lets you open the Window List.
You can open the Window List also by middle-cliking on the desktop,
in any area with no windows at all.
A side effect of opening the Window List is that its menu
is the default one, so you can get it back. Anyway you can get back
the default menu also by left-clicking on the screen background, in an area
with no windows: this un-focuses all windows and, when no window is focused,
you _always_ get the default menu.
Clicking with left mouse button or hitting keyboard `Return' on
a window name of the Window List will focus and Center the corresponding
window.
Other not-so-obvious things you can do from the Default menu are:
"Full Screen" to maximize the current window to full-screen,
RollUp to collapse a window to its title bar only, and back to normal size,
Refresh to redraw the whole display in case it gets garbled,
Raise/Lower to move the focused window to top/bottom of windows stack,
and also unfocus if moving it to bottom of stack.
You can use the menus even without a mouse: The `F12` or `Pause' keys open the menu
(to change them, edit your ~/.config/twin/twinrc, or, if you disabled support
for twinrc parser, edit server/hotkey.h and recompile)
then you can transverse the menu with arrow keys, hit `Return'
to select an entry in a menuitem or `Escape' to close the menu.
Choosing Menu -> Window -> Move lets you move the focused window with
arrows, Resize lets you resize it (still with arrows),
while Scroll lets you scroll it: use arrows for one-line scrolls and
Insert,Delete,PageUp,PageDown for one-page scrolls.
There is a small problem now: if twin intercepts the `F12` and `Pause' keys,
how can you have your programs receive them? This is what menu entries
"Send F12" and "Send Pause" are for: they send the corresponding key event
to the focused window.
Now, the next argument: Focusing and Freezing.
Even if it comes quite natural to most people to press the left mouse button
on the lower-right corner of windows to resize them, a thing you probably
don't know is that if _while holding the left button_ you also press
the middle or right button, the window will `freeze', i.e. it doesn't resize
anymore when you move the mouse, but will istantly resize when you _release_
the middle or right button. Also, while the window is `frozen', the virtual
screen doesn't scroll. The same `freeze' technique can be used while
dragging a window (to drag a window, press left button on window title).
Downside:
`Freezing' does not work if you have a two-button mouse, and twin displays on X,
and you configured the X server with Option "Emulate3Buttons".
That's a limit of your mouse / X server combination.
Other maybe not-so-obvious things are:
the button on top-left of each window, drawn as "[]", is the CLOSE button;
the button on top-right, drawn as two up-down arrows, is the TOP/BACK button:
click on it in the top window and it will become the last window;
click on it in a window behind other windows, at it will become
the top window;
the button next to top-right, drawn as "><", is the ROLLUP button:
click on it and it will collapse the window to its title bar;
click on it again and it will restore the window to its normal size;
the scrollbars are quite intuitive: click on the arrows near the lower-right
corner to scroll the window contents one line (or row) at time;
drag the `tab' (the solid white bar) to quickly scroll the window;
click on the space before or after the `tab' to scroll the window contents
one page at time.
Twin splits the concepts of top window and focused window:
left-clicking on a window will focus it, so that keypresses
will go to that window, but you will need to click
on the window's TOP/BACK button to have it become the top window. Clicking
on the window's TOP/BACK button again will Lower and UnFocus the window.
Twin also implements cut-n-paste, in the same way as linux console, xterm,
and other terminals: you select some text by moving the mouse with
the left button pressed and paste by clicking with the middle button.
Again, you can tailor (almost) any of the above features to your tastes
by editing your own ~/.config/twin/twinrc configuration file.
The file `twinrc' distributed with twin is a well commented sample
configuration you can start from.
6. External programs
If you have `twin' correctly installed and running (and eventually you
loaded the Socket Server module) you can run an external program
by typing its name, just as you do with X11 clients.
If twin is not installed yet, you will need to set LD_LIBRARY_PATH to the
directory where libtw.so.2 is: something like
export LD_LIBRARY_PATH=/lib
should work.
Also, if you don't start external programs from within a twin terminal
window, you will need to set the display. Type
echo $TWDISPLAY
inside a twin terminal, then
export TWDISPLAY=:
before running your external programs. To run external programs from
another machine, using TCP sockets, do something like
export TWDISPLAY=:
In the last case, you will also need to authorize your clients to talk
to twin. The authorization method currently used is similar to Xauthority:
the file .TwinAuth in your home directory holds some magic data that
clients use to answer the challenge received from twin. If that data
is wrong or the file doesn't exist, clients can connect to twin only
using the unix socket (TWDISPLAY=:) so they must run
on the same machine as twin; remote programs won't be able to connect.
The external programs (clients) distributed with twin are:
twattach - utility to attach/detach twin from displays
twdisplay - advanced utility to attach/detach twin from displays
twcat - twin-aware version of `cat'
twclip - a wannabe utility to manage clipboard.
For now, it's little more than test.
twlsobj - show internal server objects: windows, menus, ... Options:
-h, --help display this help and exit
-V, --version output version information and exit
-r, --recursive also show lists of parents, children, ...
-v, --verbose always show all data, even huge arrays
twevent - report twin events, like xev (X11) and mev (console/gpm)
twmapscrn - twin equivalent of Linux console tool `mapscrn'
NOTE: when started from Linux console, twin will already
load the current consolemap translation, so using twmapscrn
is often not necessary.
twsendmsg - utility to send messages to running libtw clients. Options:
-h, --help display this help and exit
-V, --version output version information and exit
--control send a msg_user_control message (default)
--clientmsg send a msg_user_clientmsg message
[--code=] set the message code (default is open (2))
[--data=] set the message data
Currently known codes for control messages are:
quit (0), restart (1), open (2)
twsetroot - customize twin background (see clients/README.twsetroot)
twsysmon - a system resources monitor (works on Linux only)
twterm - create remote twin terminal windows. Known options:
-h, --help display this help and exit
-V, --version output version information and exit
-t set window title
(you will need to enclose <title> in quotes
if it contains spaces or other special chars)
-e <command> run <command> instead of user's shell
(must be last option)
twthreadtest - a stupid demo to test libtw with threads.
twdm - a login manager, modeled after xdm/kdm. Known options:
-h, --help display this help and exit
-V, --version output version information and exit
-k, --kill kill twin server upon display detach
-q, --quiet quiet; suppress diagnostic messages
--attach use "twattach" to start display (default)
--display use "twdisplay" to start display
--envrc tell twin to run ~/.config/twin/twenvrc.sh to get environment
--suidroot tell twin to keep suid root privileges
--sgidtty tell twin to keep sgid tty privileges
--title=<title> set window title
--hw=<arg> set display hw to use (default: -hw=tty)
`twdm' can be used instead of the usual mingetty/agetty/login programs
to let a user login on a workstation console (currently tested only on Linux).
To do that, you can just type in a root shell on the console
# twdm
but this will work only until twdm is killed. For a more permanent setup,
you need to convince init that it should exec twdm instead of the usual getty.
Assuming you have a SysV flavour of init and that twdm is installed in
/usr/local/bin, a line like this in /etc/inittab should do the trick :
(you must find the line that starts getty on the corresponding tty and
replace the whole line with the one below -- of course you must replace
TERM=<...> with the actual terminal type of your workstation console)
1:2345:respawn:/usr/local/bin/twdm --quiet --hw=tty@/dev/tty1,TERM=linux
In order to correctly setup $PATH and other environment variables,
you can add `-envrc' option to twdm (tested only on Linux with bash).
The `twterm' client and the builtin terminal emulator deserve a few extra
explanations. They implement a linux terminal, so applications running
inside them will see TERM=linux, but also support two different mouse
reporting protocols: the first is the classical xterm-style reporting
(enabled with ESC [?1000h and disabled with ESC [?1000l ) which is only
capable to report mouse buttons hit/release and the window position where
they happened; furthermore, it is limited to a 255x255 window.
The second is an enhanced version which can also report mouse drags and has
14 bits data for window width and height. It is enabled with ESC [?9h and
disabled with ESC [?9l . Also, they support xterm-style escape sequence
to change window title.
Since most programs running inside a linux terminal don't expect to be able
to use the mouse with xterm-style protocol, various tricks may be needed in
order to have mouse functionality with applications running in a twin
terminal. Here are some:
Midnight Commander `mc': start with `mc -x'
Other applications: you can try to set TERM=xterm and hope to fool them.
The use of `twsendmsg' might not be obvious, so a few details can help:
every twin client creates a message port inside twin, which is used to
receive messages. These include keyboard and mouse events, window size
changes, menu activity, and some other things. Anyway, not all messages
are generated by the server. It is possible to create a message from
a client and send it to another client. This makes possible, for example,
to send a message to `twterm' saying "please open a shell window".
To send exactly this message, one can use `twsendmsg' in the following way:
twsendmsg "twterm" open
("twterm" is the name of the message port created by `twterm',
while "twin" is the name of the message port builtin into twin server)
Of course it is possible to start arbitrary commands with `twsendmsg',
not just the user's shell:
twsendmsg "twin" open "pine someone@somewhere.net"
A last note: the message port must already exist to be able
to send messages to it, so
twsendmsg "twterm" [...]
works only if there is at least one `twterm' running.
Sending messages to "builtin twterm", the message port of the builtin
terminal emulator, would work too, but only if the terminal emulator code
(term.so) is already loaded into twin. Sending messages to "twin"
instead always works, and it can auto-load term.so if needed.
You can send also other kinds of messages. A (useless?) example is
twsendmsg "twin" quit
which causes twin to exit, as if Menu -> File -> Quit was selected.
6.1. Saving diagnostic messages (logs):
twin and other programs send diagnostic messages, informations,
and most notably errors, to standard error. This is good in most
cases, but if you tell twin to use its own tty as display,
diagnostic messages may be lost or may even garble the display.
In this case, it can be useful to save diagnostic messages to some
file or device, for example another tty, or /var/log/twdm.log.
The way to obtain this depends on your shell, but with bash and many
other common shells, you can redirect standard error in this way:
$ program arguments 2>filename
The various programs distributed with twin do not change their
standard error, so for example, running
$ twdm 2>/var/log/twdm.log
will redirect all diagnostic messages produced by twdm and by programs
executed by it (twin and twattach/twdisplay) to /var/log/twdm.log.
Furthermore, diagnostic messages produced by twin are also collected
within twin itself, and can be viewed selecting Menu -> ≡ -> Messages
from the default menu.
6.2. Security Statement on Sockets:
As said above,
the authorization method currently used is similar to Xauthority:
the file .TwinAuth in your home directory holds some magic data that
clients use to answer the challenge received from twin. If that data
is wrong or the file doesn't exist, clients can connect to twin only
using the unix socket (TWDISPLAY=:<something>) so they must run
on the same machine as twin; remote programs won't be able to connect.
Also, the unix socket is set to permissions 600, so only the owner can
connect to it (at least on Linux it works this way).
The `challenge' is actually an MD5 checksum verification: server sends
256 bytes of random data; client does MD5 of that data + .TwinAuth and
sends MD5 back. If server agrees on MD5, it grants connection.
This challenge method has an important feature:
The contents of your .TwinAuth is NEVER transmitted through any socket.
So, unless your home directory resides on an NFS filesystem, you can
be sure that noone will be able to find the data contained in your
.TwinAuth by spying the network between twin and the clients you start.
On the other hand, the connection between twin and clients is NOT
encrypted, so it is easy to find out what you type and what you see
in the client windows by spying the network as above.
7. Transparent Compression
Twin and libtw transparently support gzip compressed sockets
by using the library `zlib'. If the connection between twin
and the remote programs you want to run is slow,
you may benefit from compression.
To allow compression, you need zlib installed on your system,
then ensure `./configure' found it: among the zillion of messages,
it should also print a line like
[...]
checking for zlib.h... yes
[...]
checking for deflate in -lz... yes
[...]
finally compile twin and libtw.
To actually use compression, append ",gz"
to your $TWDISPLAY like in these examples:
export TWDISPLAY=:0,gz
export TWDISPLAY=myhost.somewhere.net:5,gz
8. Attach/Detach
Twin can run without a display at all, can attach or detach from a display
on the fly, and can also run with multiple simultaneous displays.
There are various ways to temporarily close a display used by twin:
1) select `Suspend' from the `File' entry of the default menu.
This is equivalent to the normal Unix job control associated to CTRL-Z:
twin shuts down all its displays and returns to the shell it was started
from. To resume twin, just type `fg' (or send a SIGCONT to it).
This may not work if you used 2) below, because that detaches twin
from the job control mechanism used by shells.
2) select `Detach' from the `File' entry of the default menu.
WARNING: Be sure the Socket Server can be started before doing this!
Otherwise you will not be able to talk to twin at all!
In this case, twin shuts down all its displays and detaches
(by forking in the background) from the shell it was started from,
but keeps running as a daemon (with no display).
3) run `twdetach' (more explanations below for this, but in this case
it is equivalent to selecting `Detach' from the default menu).
4) select `Display' from the `≡' entry of the default menu,
watch the `Display' window pop up, choose a display from the list
and click on `Remove'.
There are two ways to have twin attach to a display
(or to ONE MORE display, as twin can use multiple simultaneous displays):
`twattach' and `twdisplay'.
Let's start with `twattach':
Basically, you run twattach specifying which display you want *twin*
to attach to.
Twin then tries to start that display by its own,
while twattach's only work is to report all messages generated by twin
during the attach (if you run twattach with the option `-q' (quiet),
then twattach has nothing to do at all).
Instead `twdisplay' works differently:
You run twdisplay specifying which display you want *twdisplay* to use.
Twdisplay tries to start that display, reporting any generated message.
If the display succeeds in starting up, twdisplay connects to twin,
registers itself as a special display, and then works as an intermediate
layer between the display it started and twin:
twdisplay sends to twin the events generated by the display,
and when it receives draw requests from twin, it calls the appropriate
functions of the display to keep it up-to-date.
The two different programs have different advantages and disadvantages:
twattach: advantages: fast, efficient, extremely lightweight.
disadvantages: completely relies on twin to be able to use
the display. For example, twin running on a host
cannot connect to `gpm' running on another,
and attaching twin to itself causes a deadlock.
twdisplay: advantages: starts up the display by its own.
This means that if you have twin running on a host,
you can use twdisplay to attach twin to the console
of another host, WITH mouse support (gpm).
Also protects twdisplay from bugs, quirks and
limitations in display drivers and libraries
needed by them: libgpm can connect only ONCE
to A SINGLE gpm, libX11 calls exit() when
receives fatal errors from X server, etc.
Using `twdisplay' to attach twin to itself works!
disadvantages: eats more CPU and memory. Not really a problem
these days.
Examples:
$ twattach --hw=X
tell the default twin (corresponding to $TWDISPLAY)
to attach to the default X server (corresponding to $DISPLAY)
$ twdetach --hw=X
tell the default twin
to detach ONE display attached to the default X server
$ twdetach --twin@:5
tell the twin corresponding to :5 to detach from ALL its displays
and keep running in the background (same as using `Detach' from menu)
$ twattach --twin@<some twin display> --hw=X@<some X display>
tell twin correspinding to <some twin display>
(for example :5, or myhost.somewhere.net:2)
to attach to the X server corresponding to <some X display>
The programs `twattach', `twin', and the X server do not need
to run on the same host as long as they have the permissions
to talk each other (see above for an explanation about how
the file .TwinAuth is used for authorization control)
$ twattach --twin@:5 --hw=tty
tell twin :5 to attach to the same tty device you are running
`twattach' on. For this to work, both `twattach' and `twin' must
be running on the same host.
$ twdisplay
autoprobe for a display, then attach twin at $TWDISPLAY to it.
The main advantage of using twdisplay is:
since it is actually twdisplay that attaches to the display,
while twin just talks to twdisplay using a socket, `twdisplay' and `twin'
may even be running on different hosts.
$ twdisplay --twin@myhost.somewhere.net:1 --hw=tty
attach twin at myhost.somewhere.net:1 to the tty device you are running
`twdisplay' on.
$ twattach --twin@myhost.somewhere.net:1 --hw=tty@-
tell twin at myhost.somewhere.net:1 to attach to its own controlling tty.
This does not work if that twin has already detached from its tty,
but you will be told that in case it happens.
$ twdetach --twin@myhost.somewhere.net:1 --hw=tty@-
tell twin at myhost.somewhere.net:1 to detach from its own controlling
tty (supposing it was being used as a display)
$ twattach --twin@:5 --hw=tty@<some tty device>,TERM=<terminal type>
tell twin to attach to <some tty device>.
In this case you must make sure no program is reading/writing
on <some tty device> (for example you might run `sleep 365d' on it)
or things will go BADLY wrong.
WARNING:
twin has no way to detect if the tty you specified is really
a supported terminal. If you attach twin to an unsupported terminal,
things might go BADLY wrong.
$ twdisplay --twin@myhost.somewhere.net:1 --hw=twin@yourhost:3,gz
attach twin running on myhost.somewhere.net:1
to another twin running on yourhost:3 and display on it.
The final ",gz" means that the connection between `twdisplay'
and the second `twin' will be compressed.
The most general syntax of twattach is:
twattach [-a|-d] [-v|-q] [-s|-x] [--twin@<TWDISPLAY>] --hw=<display>[,options]
The most general syntax of twdisplay is:
twdisplay [-v|-q] [-s|-x] [--twin@<TWDISPLAY>] [--hw=<display>[,options]]
switches have the following meaning:
-a : send attach command (default)
-d : send detach command (same as running `twdetach [args ...]')
-v, --verbose : be verbose and display all messages generated by twin
while trying to attach (default)
-q, --quiet : be quiet and display no messages
-s, --share : allow multiple simultaneous displays (default)
-x, --excl : request an eclusive display - detach all others
if you do not specify `--twin@<TWDISPLAY>', the default $TWDISPLAY will
be used.
if you do not specify `--hw=<display>[,options]', twdisplay will autoprobe
for it.
known displays are:
--hw=xft[@<XDISPLAY>]
--hw=x11[@<XDISPLAY>] or --hw=X11[@<XDISPLAY>]
--hw=tty[@<tty device>]
--hw=twin[@<TWDISPLAY>]
and known display options are:
all displays : ",noinput" to start the display as view-only;
keyboard and mouse activity on that display
will be ignored.
: ",slow" to tell twin the display is slow and output
to it should be buffered and chunked together as much
as possible (this is on by default for -hw=X , -hw=X11
and -hw=xft)
--hw=X or --hw=X11 or --hw=xft :
: ",font=<fontname>" to choose your favourite X11 font
(default: vga).
: ",charset=<name>" to inform the driver about the codepage
corresponding to the used font (default: autodetected).
: ",drag" to allow using XCopyArea as redrawing speedup.
This is off by default as on many X servers XCopyArea
is actually slower than a normal redraw.
Your mileage may vary.
--hw=twin : ",gz" to enable gzip compression on the connecting socket.
--hw=tty : ",termcap" to use termcap/ncurses interface even if other
methods are available.
: ",colorbug" use with termcap interface, if terminal does not
reset colors to white on black using ESC [ m
(or the appropriate sequence for the terminal).
: ",mouse={xterm|twterm}" to force mouse to xterm-style or
to twin-term-style in case it is not autodetected.
: ",TERM=<terminal>" to specify the terminal type.
: ",charset=<name>" to inform the driver about the codepage
used by the terminal (default: CP437).
: ",ctty" to tell twin to grab given tty as its new
controlling tty (mostly useful from twdm)
: ",utf8" to tell twin that the tty understands utf8 encoding
to display Unicode.
A common situation is the following:
You have a detached twin, whose TWDISPLAY is :2,
running on a host (say plato.alter.net),
you are sitting at the console of another host (say globe.alter.net)
and you want to attach twin on the console of globe.alter.net.
How?
Attaching twin to the X server of globe.alter.net is easy, just run
this command on globe
$ twattach --twin@plato.alter.net:2 --hw=X@globe.alter.net:0
or alternatively,
$ twdisplay --twin@plato.alter.net:2 --hw=X@globe.alter.net:0
(this requires you have the same .TwinAuth on both hosts
and that the X server on globe accepts the connection attempt,
either due to `xhost +plato.alter.net' or by having a suitable
.Xauthority on both hosts)
But attaching twin (running on plato) to the console of globe is another
matter, since that twin has no way to reach the tty devices on globe.
The easiest way is to use `twdisplay', running this command on globe
console:
$ twdisplay --twin@plato.alter.net:2 --hw=tty
There are ways to solve the problem without `twdisplay', but they
are both more complex and less functional, as they either require
using telnet or ssh from globe to plato (and thus losing the mouse)
or starting a SECOND twin, this time on globe console, and attaching
the first twin on it.
To avoid accidental problems, or to protect your twin session in a hostile
environment, twin also implements exclusive displays:
An exclusive display can be started only if there aren't already exclusive
display running, it detaches all other displays while it starts, and forbids
any other display to be attached as long as it is running.
Twdetach is unable to detach an exclusive display: the only way to quit it
is the Display window inside twin (killing the `twdisplay' process that
requested the exclusive display works too).
To request an exclusive display, you must add the option `-x' or `--excl'
to twdisplay command line. Example:
$ twattach --excl --twin@:0 --hw=tty
Exclusive displays can be started directly by twin, exactly in the same way:
$ twin --excl --hw=tty
Of course, when specifying `--excl', twin can only start one display.
Summary of twin options:
-h, --help display this help and exit
-V, --version output version information and exit
--secure forbid starting external programs
--envrc execute ~/.config/twin/twenvrc.sh and read its output
to set environment variables (mostly useful for twdm)
-s, --share start display as shared (default)
-x, --excl start display as exclusive
--nohw start in background without display
--hw=<display>[,options] start with the given display (multiple --hw=... allowed)
(default: autoprobe all displays until one succeeds)
9. Installing fonts
a. X11:
Two X11 fonts are currently distributed with twin:
vga.pcf.gz a VGA-like font (size 8x16, codepage 437)
9x19u.pcf.gz a font derived from public domain '10x20.pcf.gz' font:
it has 9x19 size and it is unicode. full X11 name is
-misc-fixed-medium-r-normal--19-200-75-75-C-100-ISO10646-1
If you want to install these fonts to use them under X,
you should do something like this (details are system dependant):
copy fonts/*.pcf.gz from the distribution to a misc fonts directory,
I used /usr/X11R6/lib/X11/fonts/misc on my system.
Run `mkfontdir' as root on the directory used.
Since you are at it, you may also add the line
9x19 -misc-fixed-medium-r-normal--19-200-75-75-C-100-ISO10646-1
to `fonts.alias' in the same directory.
Run `xset fp rehash'.
Use the command 'xlsfonts | grep vga' to see if the fonts have been
registered correctly.
This should fix some problems with twin displaying strange fonts
under X, since if twin cannot find the `9x19' nor the `vga' font,
it will fallback on `fixed', which has no pseudo-graphical characters
and makes twin look really ugly.
b. VGA text display:
To use twin on a VGA or better text display, you can use the supplied
VGA font `fonts/vgafont.raw' by typing a command like
`setfont fonts/vgafont.raw' or `loadfont fonts/vgafont.raw'
(again, details are system dependant).
As side note, if you are going to use twin on a VGA text display,
I strongly suggest to set your VGA card to something better than
the default 80x25. Some of the ways to do this are:
using SVGATextMode;
using the card BIOS;
compiling framebuffer support in your linux kernel.
10. Greetings
I hope you will like using twin as I liked writing it.
Have fun...
Massimiliano Ghilardi
<https://github.com/cosmos72/>