Table of Contents



ggivnc - a VNC client using GGI libraries for input/output


ggivnc [-adhiv46] [-e <encodings>] [-E <endian>] [-f <pixfmt>]
       [--gii <input>] [-p <password>] [--rfb <version>]
       [-s <security>] [-b <interface>] -l[<display>|:<port>]
ggivnc [-adhiv46] [-e <encodings>] [-E <endian>] [-f <pixfmt>]
       [--gii <input>] [-p <password>] [--rfb <version>]
       [-s <security>] [server[:<display>|::<port>]]


In the above, the square brackets denote optional arguments, but if server contains a colon or starts with a literal “[”, quote it with literal square brackets to have ggivnc not interpret part of the server name as the display or port. E.g. [::ffff:] (for IPv6 users).


ggivnc makes a TCP connection to the specified VNC server and expects the server to communicate with the remote framebuffer (RFB) protocol. ggivnc can also operate in reverse and listen for connections from VNC servers. ggivnc supports RFB protocol versions 3.3 through 3.8. The display can optionally be specified, but if it is not display 0 is the default. The display is simply a shortcut for which TCP port to connect to, where the base display 0 maps to TCP port 5900. E.g. display 4 is equivalent to port 5904. An alternative is to directly specify the port. In reversed mode (when listening), the base is moved from port 5900 to port 5500.

The remote framebuffer is displayed on the selected libggi target. See libggi(7) for how to select the libggi target.

ggivnc supports the following RFB encodings:

Raw, CopyRect, RRE, CoRRE, Hextile, Zlib, Tight, ZlibHex, ZRLE, DesktopSize, LastRect, GII, DesktopName and WMVi.

The encodings are described in a few words below, in the ENCODINGS section.

Pressing F8 presents a menu with options to:

  • Close ggivnc.
  • Pass on F8 to the remote end.
  • Request a full update.
  • Send Ctrl-Alt-Del to the remote end.
  • Pass on hotkeys to the remote end.
  • Send the content of the clipboard to the remote end.
  • Display an about dialog.


-a, —alone
Alone - don't request a shared session.
The default, request a shared session.
-b, —bind <interface>
Only allow connections on <interface> when operating in reverse mode (i.e. listening). See -l, —listen.
-d, —debug
Increase debug output level. If this option is given multiple times, more debug output is generated.
-e, —encodings <encodings>

Give a comma separated list of encodings that should be requested from the server, in order of preference. If the -e option is not given, a preferred encoding is selected based on throughput.

The available encodings are: raw, copyrect, rre, corre, hextile, zlib, tight, zlibhex and zrle.

In addition to the above encodings, the pseudo-encodings desksize, deskname, lastrect and wmvi can also be selected and 10 tight encoding quality levels are also available, i.e. quality0 - quality9 where quality9 is better quality for faster data links. Also, 10 tight encoding compression levels are available, i.e. zip1 - zip9 where zip9 is slower with higher compression ratio. zip0 lets the server decide the compression level. Last but not least, the gii pseudo-encoding is available.

Example: -e copyrect,hextile,desksize,deskname,lastrect

-E, —endian <endian>
Specify big or little to override the autoselection of the on-the-wire endianess to use.
-f, —pixfmt <pixfmt>

pixfmt is either r<bits>g<bits>b<bits> (in any order, insert p<bits> as desired for padding), c<bits>, local or server.

r<bits>g<bits>b<bits> indicates that the on-the-wire pixel format will be this specific true-color variation.

c<bits> indicates that the on-the-wire pixel format will be palettized.

local (the default) indicates that the on-the-wire pixel format will be identical to that of the current GGI target.

server indicates that the on-the-wire pixel format will be whatever the server prefers. The on-the-wire endianess will in this case also be whatever the server prefers, unless the -E option is also used.

—gii <input>
Specify an extra gii input target to load.
-h, —help
Help - prints a short help text
-i, —no-input
No input - peek only, don't poke
-l[<display>|:<port>], —listen[=<display>|=:<port>]
Operate in reversed mode, i.e. listen for connections instead of making a connection.
-p, —password <password>
Specify a file where the password for the connection is stored. Beware, max 8 (7-bit) characters in the password are used.
—rfb <version>
Specify the maximum RFB protocol version to use. Supported RFB protocol versions are 3.3, 3.7 and 3.8.
-s, —security-types <security-types>

Give a comma separated list of security types that should be allowed, in order of preference. If the -s option is not given, ggivnc prefers security type none over vnc-auth.

The available security types are: none, vnc-auth, tight

If a list of allowed security types is given and the server does not support any of the allowed security types, ggivnc will try to request the first security type in the given list, on the off chance that the server will allow it even if it is not saying so.

The security types are described in a few words below, in the SECURITY TYPES section.

-v, —version
Version - prints the ggivnc version
-4, —ipv4
Only attempt connections using IPv4.
-6, —ipv6
Only attempt connections using IPv6.


Below follows a short description of each of the supported encodings.

This encoding is a must, the server may always use it. Each update is a straight linear framebuffer dump.
This encoding instructs the client to copy a rectangle from some other place in its local framebuffer.
The Rise and Run-length Encoding divides the updated rectangle in small(er) rectangles, where each of these rectangles are of a solid color.
Compact RRE is a variation of RRE, where the largest possible solid rectangle is 255x255 pixels, generally allowing fewer bytes wasted in the overhead specifying the size of all rectangles.
The updated rectangle is divided into 16x16 pixel "tiles". Each tile is then encoded using either a raw encoding or yet another variation of the RRE concept - this time with even fewer bytes wasted in the size overhead and also some shortcuts in the color selection.
This encoding is just like the Raw encoding, but every update is compressed using the zlib deflate algorithm.
The updated rectangle can be encoded in one of three ways: Fill, jpeg or Basic. Fill fills the rectangle with a solid color and jpeg encodes the rectangle with jpeg. The basic subencoding optionally applies one of two filters to the raw data before feeding the data to one of four zlib streams. The available filters are Palette and Gradient. The Palette filter stores each pixel as one byte unless there are only two colors in the rectangle, it then uses one bit per pixel. The Gradient filter uses the three pixels above and to the left to predict the current pixel, and stores the difference between the real pixel value and the prediction.
This encoding is just like the Hextile encoding, but each tile may be compressed with one of two zlib streams. One stream is used for raw tiles, the other for RRE tiles.

This is a tiled encoding where each tile is 64x64 pixels. Each tile is encoded using one of these subencodings: Raw, Solid, Packed Palette, RLE or Palette RLE. The Packed Palette subencoding may be used when there are few colors (16 or less) in the tile. The pixels are represented with 1, 2 or 4 bits depending on the size of the palette, and the pixels are then packed as tightly as possible within bytes. The RLE subencoding stores the length of horizontal runs, and their color, while the Palette RLE subencoding does likewise, but using palette lookup (max 127 colors) in order to reduce the color specification overhead.

The whole ZRLE rectanle is then compressed using the zlib deflate algorithm.

The DesktopSize pseudo-encoding is used by the server in order to indicate framebuffer (or desktop) size changes to the client. See the WMVi pseudo-encoding below for a more capable pseudo-encoding.

The LastRect pseudo-encoding enables the server to start to transmit an update consisting of several rectangles, without knowing exactly how many rectangles the update will eventually consist of. It may start transmitting the update, and when it is done it just sends a fake rectangle saying that there are no more rectangles in the update.

In some situations this enables the server to start transmitting the update before it has completed all the work needed to calculate the contents of the update.

The gii pseudo-encoding provides enhanced input device handling, with support for relative pointer movement, proper mouse wheel support, more pointer buttons, flexible keyboard handling, and support for more obscure devices such as joysticks, game pads, racing wheels etc.
The DesktopName pseudo-encoding is used by the server in order to indicate changes in the desktop name (as presented in the title bar of the ggivnc window, if ggivnc is running on a windowed GGI target such as display-x).
The WMVi pseudo-encoding can be viewed as a more capable pseudo-encoding than the DesktopSize pseudo-encoding. In addition to indicate framebuffer size changes, it also indicates on-the-wire pixel format changes.


Free for all, no password, no encryption.
The client uses the given password to encrypt (using DES) a random challenge issued by the server. The server checks if the client has the correct password. However, the maximum length of the password is 8 characters, and the connection remains unencrypted.
This is a generic protocol extension designed by the TightVNC project. It provides means to specify tunneling, authentication, what additional message types the server understands, and what encodings the server can use.


See libggi(7).


The application will simply exit when protocol errors are detected.

If the remote framebuffer is larger than the local GGI target, scrollbars are provided to select which part of the remote framebuffer to view, but only if ggivnc has been built with support for this. Without scrollbar support, ggivnc will pan the remote framebuffer when the mouse is moved close to a border.

If the server argument is not given, a dialog will prompt for what server to connect to, but only if ggivnc has been built with support for this. Without this support, ggivnc requires that the server argument is given on the command line.

Not all targets support passing on hotkeys to the remote end.

The -4 and -6 options are only available if ggivnc has been built with support for this.


The reason ggivnc came about was to fill the need of a companion to the VNC target in libggi. All existing VNC code was at the time of writing and to the best of my knowledge GPL and originating from the original AT&T code base (either that, or hidden from sight). This VNC client is an implementation from scratch.


  • There is no automatic pixel format selection mechanism.
  • Only the first connection is handled when operating in reversed mode, i.e. when listening.


The Tight encoding uses the jpeg library from the Independent JPEG Group.


Peter Rosin <>


libggi(7), libgii(7)

Get ggivnc at