NAME
    gpm-root  - a default handler for gpm, used to draw menus on the root
    window

SYNOPSIS
    gpm-root [ options ]

DESCRIPTION
    The program `gpm-root' is designed to handle Control-Mouse events to
    draw menus on the background of the current tty. The actual menus are
    described by a configuration file in the user's home directory.

    Please note that `gpm-root' needs to run with Linux 1.1.73 or newer,
    because  previous kernels lack some screen handling capabilities
    required by the program.

    The program uses the files `/dev/vcs*' to draw to the console screen.
    These are available only from kernel 1.1.81 onward. If you miss those
    device nodes, you should create them using `create_vcs' in the distri-
    bution directory. The tool won't run with kernels older than 1.1.81,
    because they lacked a full screen dump/restore capability.

    Available command line options are the following:

    -m number
    Choose the modifier to use (by default: `control'). The modifier
    can be provided  either  as a number or as a symbolic string.
    Allowed strings are `shift', `anyAlt', `leftAlt', `rightAlt',
    `control'.

    -u   Deny using user-specific configuration files. With this option
    on, only `/etc/gpm-root.conf' will be used as a source of con-
    figuration information. This option is intended for those system
    administrators who fear security could be broken by this daemon.
    Things should be sufficiently secure, but if you find a hole
    please tell me about it.

    -D   Do not automatically enter background operation when started,
    and log messages to the standard error stream, not the syslog
    mechanism. This is useful for debugging; in previous releases
    it was done with a compile-time option.

    -V verbosity increment
    Raise the maximum level of messages that will be logged. Thus a
    positive argument has the effect of making the program more ver-
    bose.  One can also give a negative argument to hush the pro-
    gram; however, note that due to getopt(3) rules a negative argu-
    ment must follow the option with no space betwixt (that is,
    `-V-1' but not `-V -1').  The argument is optional and its
    default value is 1.

    Each time a menu is drawn, the configuration file is reparsed if it has
    changed. This allows modification of personal setup without reinvoking
    the daemon.

    The actual configuration file is better introduced by looking at your
    `/etc/gpm-root.conf'.

    The syntax for the file won't be described here, being it quite appar-
    ent from the example above. Blanks and newlines are unused in parsing
    the file, and the layout of the file is free. Comments are allowed in
    the file: any hash mark (`#') found at the beginning of the line or
    after white space makes the parser discard anything up  to the next
    line. To insert quotes (`"') in strings precede them with a backslash.

    Note that recursive menus are allowed, to any level of recursion.

    Keywords belong to three groups: the button keyword, the  cfg keywords
    and the action keywords. They are all described in the table below:

    button number menu
    The `button' keyword is used to introduce a menu. It is followed
    by the number of the relevant button (1=left,  2=middle,
    3=right),  an open brace, a menu and a closed brace. A menu is
    made up of cfg statements, followed by action statements. Cfg
    statements can come in  any order, while the order of action
    statements tells the actual order in which actions will appear
    on the screen, top to bottom.

    The following statements belong to the cfg set.

    name string
    If the `name' keyword is present, the specified string will be
    used as the name for the current menu.

    background color
    This statements is used to specify the background  color to be
    used in the current menu. The color can be specified with one of
    the eight canonical strings `black', `red', `cyan' etc. The
    background defaults to black.

    foreground color
    This statements is used to specify the foreground color for menu
    items. Its value defaults to `white'. An optional `bright' key-
    word can appear before the actual color.

    border color
    `border' is used to specify the border color for the menu. Its
    value defaults to `white'. An optional `bright' keyword can
    appear before the actual color.

    head color
    `head' is used to specify the foreground color for the title of
    the menu. Its value defaults to `white'. An optional `bright'
    keyword can appear before the actual color.

    The following statements belong to the action set.

    string f.fgcmd cmdstring
    When the  mouse button is released above the corresponding menu
    item, the cmdstring is pasted in the keyboard queue of the cur-
    rent console. This is not yet implemented.

    string f.bgcmd cmdstring
    When the  mouse button is released above the corresponding menu
    item, a shell (`/bin/sh') is forked to execute the specified
    command, with `stdin' connected to `/dev/null', and `stdout',
    `stderr' connected to the active console.

    string f.jptty ttynumber
    When the mouse button is released above the corresponding menu
    item, the console is switched to the one specified. The ttynum-
    ber must be specified as a string. Any tty can be  reached this
    way, even those which are not accessible via the keyboard.

    string f.mktty ttynumber
    When the  mouse button is released above the corresponding menu
    item, an unused console is selected, and `/sbin/mingetty' is
    executed in it.  The current console is switched to the newly
    opened console. I use this command to save kernel memory by
    opening a single console through `/etc/inittab' and requesting
    the others only when i need to login.

    string Whole-menu
    A menu can directly follow the label string.  When the  mouse
    pointer leaves the menu frame at the level of string, a second
    menu is posted on screen.

    string f.lock
    When the mouse button is released above the corresponding menu
    item, the keyboard and the screen are locked, and only the lock-
    ing user or the superuser can unlock them. This is not yet
    implemented.

    string f.load
    The current loadavg when the menu is posted is concatenated to
    string to build the actual message displayed on screen. Nothing
    happens at button release.

    string f.free
    The free memory and swap when the menu is posted is concatenated
    to string to build the actual message displayed on screen. Noth-
    ing happens at button release.

    string f.time
    The current time is formatted with strftime(3), according to
    string. The resulting string is the actual message displayed on
    screen. Nothing happens at button release.

    string f.pipe cmdline
    When the  mouse pointer  leaves the menu frame at the level of
    string, a message box is posted on screen showing the last ten
    lines  of the output of cmdline. cmdline is executed by
    `/bin/sh'. This is not yet implemented.

    string f.nop
    This does nothing, it only displays string on the menu.

    The `HOME', `LOGNAME' and `USER' environment variables are setup to the
    values for the  invoking user  before  spawning an external process
    (`f.bgcmd', `f.pipe'). The current directory is always `/'.

BUGS
    Known bugs have been fixed. In particular, if you invoke `gpm-root'
    right after `gpm', it will delay a few seconds before trying to connect
    to the daemon.

AUTHOR
    Alessandro Rubini <rubini@linux.it>

FILES
    /dev/gpmctl   The socket used to connect to gpm.
    /etc/gpm-root.conf The default configuration file.
    $(HOME)/.gpm-root  The user configuration file.
    /dev/vcs*   Virtual Console Screens

SEE ALSO
 gpm(8)

    The info file about `gpm', which gives more complete information and
    explains how to write a gpm client.