x2gpm − paste X selections into the console using gpm


x2gpm [−−options]



Operate on all virtual consoles (requires root permissions).

−−display disp, -d disp

Connect to the given X display disp, or by default use the DISPLAY environment variable. Either this option or DISPLAY must be given.

−−pidfile filename

After forking into the background, write the process ID number of the child into filename (a text file).


Print some extra diagnostics and logs, and show syslog messages on stderr as well as the syslog.


Don’t fork into the background. This is mainly useful for testing.


Print the program version, and exit. With −−verbose −−version also print the gpm library and gpm server versions.


The x2gpm daemon sets up mouse Control-Button3 (the right hand button) to paste X Windows selected text (text marked for cut and paste there) into a console tty.

x2gpm forks itself into the background at startup, so a typical invocation is as follows, run from a console tty screen (and accessing X server :0).

x2gpm −−display :0

The paste works as if you typed the text, so what it does depends entirely on the program reading; perhaps it’s an editor, perhaps a command shell. For pastes of non-ASCII characters, the charset used is the locale setting when x2gpm was started, or if the console keyboard is in utf-8 mode then utf-8 (see kbd_mode(1) and unicode_start(1)).

The mouse button is read with the gpm mouse server. Gpm-enabled programs running in the foreground and doing other things with that button will override x2gpm.

If you have root permissions you can use the -a option to have a single copy of x2gpm operate on all console virtual terminals, no matter who’s logged in to them or logged in to the X server.

x2gpm −a −−display :0

The X server is not contacted until required, so x2gpm can be started before X. For an ordinary user the X authority data is taken from the ~/.Xauthority file in the usual way. For -a as root, the authority file of the user currently logged in to the server is used (identified per utmp(5)).


When running as an ordinary user the only danger is to that user, since x2gpm is not setuid. Even then the risk is only from a malicious program which has already got to the X server and puts something bad in the selection at the moment the user presses paste.

When running as root with -a to work on all console screens, again the danger is from a program manipulating the selection, but in this case the paste could go into a different user’s console tty (perhaps root’s).


If a paste can’t be done for some reason then the console bell is sounded. This is usually because there’s no X selection active.

When x2gpm is in the background, error messages are sent to the syslog(3) facility, which generally goes to file /var/log/syslog depending on syslog.conf(5) settings.

When running with -a for all console screens, one of the more obscure error messages is a failure to connect to the server with "No protocol specified". This is a message from the server and it refers to no successful authorization protocol (.Xauthority etc). Usually this means x2gpm has not determined the logged-in user and so has not supplied a correct .Xauthority.

x2gpm creates an unmapped window to receive the X selection. It has some usual WM_CLASS and WM_NAME properties for identification by external programs like xrestop(1). The X connection and window are not created until the first paste.



Default X server to copy from.


When running without -a, the location of the .Xauthority file for server access. Default $HOME/.Xauthority.


/dev/tty, /dev/console

Console screen devices.


X connection authority data taken from the invoking user, or from the logged-in user under -a.


User accounting database, for determining the logged-in user (both the console screen and X).

For -a be sure xdm or its equivalent adds a utmp entry. This is normally the default but can be disabled (/etc/X11/xdm/Xstartup or equivalent for other display manager). x2gpm looks for the display name in the line field, or for "console" in the line field and the display name in the id field.


Usual destination for errors and warnings from x2gpm.


Only a single X display is supported.

Pasting in the other direction, from the console into X, is not supported. The console selection is managed by the kernel, and as of linux kernel 2.6 is not directly offered back to user processes (a possibility would be to read the screen and replicate the word/line algorithms used in the selection).

If x2gpm is not running then Control-Button3 is the same as plain Button3, meaning a paste of the kernel selection. It can be a little confusing, or even dangerous, to get a paste of something unexpected.


x2gpm exits with status 0 if it successfully starts, forks into the background, and connects to the gpm server, or non-zero if not.


gpm(1), X(7), kbd_mode(8), unicode_start(8), syslogd(8)




Copyright 2001, 2002, 2007, 2008, 2010, 2013, 2015 Kevin Ryde

X2gpm is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

X2gpm is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with X2gpm; see the file COPYING. Failing that, goto http://www.gnu.org/licenses/