gtmess − MSN messenger client


gtmess [options]


gtmess is an MSN messenger client, which allows you to use the MSN messenger service. It is a console application that uses the curses library to present a friendly user interface. This manpage corresponds to version 0.97.


−h, −−help

Short help.


Assigns the value to the configuration variable.


Print the program version and CVR string to stdout and exit.


The following list shows all configuration variables in alphabetic order. The value of a variable is either an integer or a (line−terminated) string of characters. In the following descriptions, N represents an integer value, S represents a character string value and B represents a boolean value, a special case of an integer value with only two possible values, 0 and 1. 1 stands for True and 0 for False.

When N is 2, the user−defined contact aliases are displayed instead of nick names. A value of 1 displays aliases only when nicknames are too long (see max_nick_len variable) or when nicknames contain the email address (which is very irritating). A value of 0 disables the use of aliases completely and nick names are always displayed. User−defined contact aliases are stored into ~/.gtmess/aliases (see the FILES section). This variable affects the use of aliases everywhere but the notification window. See also the notif_aliases variable. The default value is 1.


When enabled, the contact list is selected automatically when the last chat window closes. The default value is 1.


When enabled, the login procedure starts as soon as the client is invoked, provided that login and password variables are nonempty. The default value is 1.


If enabled and a certificate cannot be verified against the list of trusted certificate authorities (see the FILES section), the user is asked if the login process should continue. Three options are given, Yes, No and Always. The meaning of each option is obvious. The login procedure requires more than one SSL connection, so option Always means that successive SSL connections will also continue upon unverified certificates. If this option is disabled, then the procedure always continues without asking the user, even if certificates cannot be verified. The default value is 1.


Sets initial color mode. Possible values are 0, 1 or 2. With 0, color is selected automatically (according to curses). 1 forces color mode, while 2 forces black and white. The default value is 0 (automatic).


Like cert_prompt, the user is asked if the login process should continue, when the common name does not match the host name upon the initialization of an SSL connection. The default value is 1.


Sets the character encoding to be used for displaying the text on the console. S is the name of the encoding. To see all valid encoding names, look at the output of the iconv −l command (on systems that provide it). If S is *locale* then the console encoding is that of the LC_CTYPE property of the current locale. The default value is *locale*.


Sets the consumer versioning (CVR) string that is sent to the server during the login process. This string provides information about the client. For more information you should look at the protocol specification. The protocol requires (from version MSNP8 and above) your login account to be the last part of the CVR string. Since gtmess uses MSNP9, your login account is appended automatically at the end. The default value is computed at configure−time and is of the following form:

0x0409 <system> <os−version> <architecture> GTMESS <clientversion> MSMSGS
For example: 0x0409 Linux 2.6.8−1−686 i686 GTMESS 0.9 MSMSGS.


Ignore ‘Connection reset by peer’ error messages in chat windows. These messages may occur very often as the server closes inactive connections. Therefore, they are not displayed by default.


The nickname chosen by the user is not stored permantently on the server any more, due to protocol changes concerning MSNP12. When this option is set, gtmess sets the nickname to S just after login. By default, this option is not set (empty string) which means that gtmess will not force a nickname change upon login. In this case the server will provide the stored nickname which could be either a proper nickname (which was stored by some msn client supporting a newer protocol version) or a nickname consisting of the email address of the account.


Ignore gtmess−specific messages that are substrings of S. To accept all such messages, leave S empty. To ignore all such messages, use the special value *all*. By default, all such messages are accepted.


If greater than zero, specifies how many seconds should pass without the user pressing any key before his/her status is automatically set to Idle. If N is zero, this feature is disabled. Note that the status is automatically set to Idle only if the previous status is Online. The default value is 180.


Sets the initial status after login. For the MSN Messenger protocol N can be a number from 0 to 8 representing the following statuses: 0 = Offline, 1 = Appear Offline, 2 = Online, 3 = Idle, 4 = Away, 5 = Busy, 6 = Be Right Back, 7 = On the Phone, 8 = Out to Lunch.
The default value is 2 (Online).


If disabled, others cannot invite you to conversation windows because the client does not respond to the invitations they send. So, if you want to chat, you have to invite others to the conversation windows yourself. If enabled, then gtmess automatically accepts invitations to switchboard sessions. Note that this option overrides the BLP setting which is stored at the server and is about users not on your forward list. This option is enabled by default.


If greater than zero, the client sends a ping request in every N seconds. This will help to keep the connection alive on some networks. The default value is 60. Note that due to changes in the protocol, the server is more willing to close inactive connections. You are not advised to set this option too low.


Sets the default login account. If S does not contain an ‘@’ character, then the string is appended.


If enabled, network traffic between the client and the notification server is recorded into file ~/.gtmess/msn.log. The default value is 0.


Sets console logging level. 0 disables logging, 1 enables switchboard window logging, 2 enables notification window logging, and 3 enables both. Log files are stored into ~/.gtmess/account/log/ in a per−contact scheme. The notification window messages are stored in the special file _nserver.log. This option is disabled by default.


Specifies the maximum allowed nickname length before displaying the alias. If N is 0, then aliases are displayed only if the nickname does not fit on a single line of the contact list window. The default value is 0.


Due to a strange bug of gtmess (or maybe feature of the openssl library), you frequently get ‘socket read error’ upon initial login attempts. The error seems to go away just by retrying. Gtmess will retry N more times, before giving up. The default value is 4.


Defines the client behavior on unrecognized messages. If N is 0, then those messages are silently ignored. If N is 1, then the type of the message is displayed, and if N is 2, the whole message is displayed. This option is useful for development purposes. The default value is 0.


If N is greater than 0, gtmess notifies you when a new message is received even when the corresponding chat window is in the foreground. This feature is useful in graphical environments where the gtmess (console) window may not be visible all the time. However, you will not be notified if less than N seconds have passed since the previous message. This is to avoid too many notifications that might be annoying. In fact, if N is 1, then the extra notification will occur only when the user is in Idle mode. The default value is 1.


Specifies the port number the MSNFTP server is listening to. The MSNFTP server is a thread that runs in the background and enables outgoing file transfers by allowing incoming connections. A value of 0 disables the server. The default value is 6891.


Specifies a set of statuses that the user may be in without receiving any sound or popup notifications. For example, if a user is Busy, having notification windows pop up all the time might be annoying. Each status corresponds to a bit of N in the order presented in the paragraph describing initial_status. The default value is 368 which stands for the set of statuses {Away, Busy, Be-Right-Back, Out-To-Lunch}, as its binary representation is 101110000.


This variable has exactly the same meaning as the aliases variable. It affects the use of aliases in the notification window. The default value is 0.


If enabled, only contacts with online status are shown on the screen. The default value is 0.


Sets the default password. The password should be given in obfuscated form. See Options/Password for more information.


This option caches the default passport login server, which by default is, in order to speed-up the login process. When this option is set to the empty string, a server will be requested from


Enables/disables the popup notification window, each time launching the script defined by the pop_exec variable. The default value is 1.


Sets the script to be used for notification windows. For Linux systems, the default value is which notify-send >/dev/null 2>&1 && notify-send gtmess ’%s’ > /dev/null 2>&1 which corresponds to the notification scheme. For Darwin/MacOS the default value is which -s growlnotify && growlnotify -a gtmess -t ’%s’ -m gtmess which makes use of the Growl notification system. The provided gtmess−notify script (see also the corresponding manpage) can be launched by specifying the following string: test -n "$DISPLAY" && which notify-send > /dev/null 2>&1 && notify-send gtmess ’%s’ > /dev/null 2>&1. In this case, make sure that gtmess-notify is already running (that is notify.pip is opened for reading), otherwise an attempt to write to notify.pip will block!

Note that this string will be passed to system() and only a single ‘%s’ is allowed which will be substituted with the message string. Single quotes in the message string will be replaced by spaces. Leaving this variable empty is another way to disable popups.


Enables/disables safe history browsing for the editboxes. When enabled and the editbox contains text that does not exist in the history buffer, the history browsing (up/down arrows) is disabled. This is to prevent the user from inadvertently pressing the arrow keys and losing some recently typed text. The default value is 1.


Prevents the user from inadvertently closing a chat window containing very recent messages. It does so by not allowing the user to close a window when there are messages that have appeared during the last N+1 seconds. A value of -1 disables this option. The default value is 0.


Sets the initial server to connect to. For the MSN Messenger protocol, this can be a dispatch or a notification server. S is of the form R hostname [ :port ]. If port is not specified, 1863 is assumed. The default value is


Skips subsequent ‘..... says:’ prefixes in a chat window from the same user, when the user messages are less than N seconds apart. The purpose of this option is to allow for more text in the chat window suppressing redundant prompts. The default value is 20.


Sets the location of the sound effect (.wav) files. The default value is *data* which corresponds to the snd/ directory in the data prefix, usually /usr/local/share/gtmess.


Sets the playback program for the sound effects. The default value on Linux systems is /usr/bin/aplay -Nq %s > /dev/null 2>&1 & which corresponds to the playback utility of the ALSA system. On Darwin/MacOS systems, the default value is /usr/bin/afplay %s > /dev/null 2>&1 & which corresponds to the system’s audio playback utility. Note that this string will be passed to system() and only a single ‘%s’ is allowed which will be substituted with the full path of the audio file. An empty string disables this option (which is equivalent to setting sound to 0).


Sets sound mode. N can be 0, 1, 2, 3 or 4. 0 disables all sound, 1 produces always a (console) beep, while 2 plays sound effects (using the external command defined by snd_exec). Value 3 produces pcspeaker sounds using the external program beep, and value 4 produces pcspeaker sounds by directly accessing the speaker on linux systems. However, this last option requires special privileges and might not work at all, or work only as root. It works in linux VTs, however (i.e., ctrl-alt-F1). The default value is 1 (beep). There are 6 sound effects that correspond to various events (guess from the name): online.wav, offline.wav, newemail.wav, type.wav, ring.wav, meout.wav.


If enabled, the contact/group lists are cached for future use. This option seems to have no meaning nowadays, as the msn server always rejects the cached version of the list. It has been disabled in this version of the client and may be removed completely in the future. The default value is 0.


Sets how often typing notifications are sent. It is the time interval in seconds. The default value is 5.


Sets how the nicknames are updated on the msn server. When a contact is initially online or changes his/her nickname while online, the server lets you know about his/her nickname. Gtmess uses the new nickname when provided, otherwise it uses the last nickname stored on the server (on your forward list). A value of 0 never updates nicknames, and a value of 2 always updates modified nicknames upon logout. A value of 1 updates nicknames only if they do not contain the email address. Note that you can always update the nickname of a specific contact manually (rename function). The default value is 0.


Sets the command line for the url browser. This typically launches a web browser to open urls that a users sends to you. Those urls are automatically parsed and displayed in the transfers window. The default value is opera --remote ’openURL(%s,new-page)’ >/dev/null 2>&1 & for Linux, which corresponds to opening the url using the Opera web browser. Under Darwin/MacOS, the default value is /usr/bin/open ’%s’ > /dev/null 2>&1 which will open the url with the default web browser. As in snd_exec, only one occurrence of ‘%s’ is allowed that will be replaced by the url. An empty string disables this option.


The screen is divided in 7 parts. Four lines and three windows.

The first line of the screen displays your nickname, your account and your status. The right−hand corner shows the system’s clock (local time).

The bottom line displays the copyright string and the menus or the input boxes.

On the right is the contact list window. On the left of the contact list window is the switchboard (chat) window. Right below the switchboard window is the messages or notification window. This window displays various messages and errors from the operating system, as well as the notification server.

The switchboard window is separated from the messages window by two lines. The first line is the editbox where you type your text when you chat. The second line is a kind of window−bar that displays a character for each open switchboard window. The window bar is displayed in three different modes, depending on the number of open switchboard windows:


In this mode, each window is represented by the name of the first contact that joined it. The name of the selected sb window (which is displayed on top) is enclosed in square brackets. Braces instead of square brackets denote that the window has unread messages (something got typed in the window while it was in the background and the user has not seen it yet).


The selected switchboard window is represented with an ‘O’. A ‘−’ represents a switchboard window that is open but not on the foreground, while a ‘+’ means additionally that the designated window has unread messages .


If there are too many open windows, then the window bar displays only the number of the current window. It also displays how many windows exist on the left and on the right of the current one and how many of them have unread messages. The 5 numbers displayed correspond to these quantities respectively: left_unread, left, current, right_unread, right.

In the following description of the keyboard controls, ‘^’ denotes holding CTRL, while ‘$’ denotes holding SHIFT. ‘@’ denotes holding ALT (or mod1 or pressing ESC first).

The functions of the main menu can be accessed by pressing ESC or F9 first, or by holding down the default modifier key (ALT) and then pressing one of the following keys (case insensitive):


Connect to server


Change status


Manage contact/group lists


Server functions




Invite a contact from your Forward List to the active switchboard window. This is actually a shortcut for R Alt−L−F− contact −I, although only online contacts are shown. An alternative way to invite a contact is to first enter contact list mode by pressing TAB and then pick a contact by pressing ENTER on it.


Write a note in the notification window


Quit the program


Enter special client command (try "help" to see a list). This function presents a simple command-line interface to gtmess. This feature, although now in preliminary form, is intended to provide scripting capabilities in future versions.

The shortcut key for the menu is shown underlined. Some menu entries may display a nested menu. Only selected menu entries are explained in this document:


List management. There are four lists in this protocol version. Forward List (FL) which is your contact list, Allow List (AL) that contains contacts that can see your online presence (normally AL contains most of your FL), Block List (BL) that contains blocked contacts and finally, Reverse List (RL) that contains those who have added you in their forward list. When you are working with lists, you are presented with a contact selection menu.


add contact to BL and remove from AL


add contact to AL and remove from BL


change the name of the contact (see also the update_nicks variable)


remove contact from all groups (a contact may belong to no particular group)


the contact to another group


the contact to a different group


the contact to the current switchboard session

Lists/Forward/Per-contact settings

Manage contact-specific settings. Currently there are two settings for each contact. Notifications (enabled by default) toggles the popup windows and sound effects for the selected contact (i.e., when somebody keeps logging in and out, it can be quite irritating). Ignored option (disabled by default) causes gtmess to ignore the contact’s requests to start a chat with you. It might appear to the other party that there is no response from the network. In this mode, conversations can be initiated only by yourself.


the contact to your forward list, too (usually you ’ll do this just after somebody has added you to his/her forward list)


the contact (you don’t have to add the contact to your forward list if you don’t want to, you can block him/her instead)


In this list you manage pending add requests.


remove all contacts in a group (use with care!)


a new contact or create a new group

Lists/Export aliases

export the forward list into ~/.gtmess/aliases so that you can edit it

Lists/Clean up

helps you remove obsolete entries from your contact lists. Shows which contacts have removed you from their contact list, so that there is no point in having them in your FL, AL and BL. Note that this is 100% accurate anymore, due to protocol changes. Consequently, you can having some contact in your FL while not in RL. Having a contact in your AL while not in RL may be pointless unless you have disabled the "All others" (BLP) flag. Similarly, having a contact in your BL while not in RL might have no meaning, unless you have the BLP flag enabled and that contact is disturbing you. Ideally, there should hold AL + BL = RL, that is each contact in the reverse list is either blocked or allowed. Occasionally, you will have same PL (Pending List) requests that you must decide whether to add or block.


set the nickname

Server/Personal msg

set the Personal Message, usually displayed after the nickname

Server/RL Prompt

prompt when others add you to their forward list. This option is stored on the server.

Server/All others

allow others (not on your forward list) to start conversations with you. This is also referred to as the BLP flag. This option is stored on the server.


set the value of a configuration variable; takes effect immediately


all configuration variables


configuration variables into ~/.gtmess/config; in fact, only those variables with values other than the default are written


Obfuscates the given password, so that you can store it in the configuration file. While this cannot be considered SAFE, it would prevent someone from stealing your password just by looking in your configuration file for a few seconds.

Options/(1)-(6) Sound test

By pressing the number keys ‘1’ to ‘6’, you can test the different sound effects.

or arrow left/right

previous/next entry

{} or home/end

first/last entry

<> or PgUp/PgDn

page up/down (skip many entries)




check (for checkable items)


cancel or return to parent menu

underlined letter

shortcut for selection


cancel all menus (no return to parent)



new switchboard (chat) session


leave current switchboard session and close the window


leave current switchboard session, but keep the window open


toggle between chat windows and contact list menu


previous switchboard session


next switchboard session


next switchboard session that has unread messages


scroll down switchboard window


scroll up switchboard window


participant list scroll down (participants in chat session)


participant list scroll up

or arrow DOWN

next contact

[ or arrow UP

previous contact


new switchboard (chat) session


leave current switchboard session and close window


invite contact to current session (i.e. after ^N)


invite contact to current session & leave menu


contact information


invoke a context menu regarding the selected contact


new chat session & invite contact & leave menu


block/unblock contact


toggle ignore contact


toggle between chat windows and contact list menu


contact list scroll down


contact list scroll up

Type any string and press enter to send it to server (talk). While you are typing, typing notifications are being sent in time_user_types sec intervals. If the string you type begins with ‘/’, then it forms a special command (and typing notifications are not being sent while you are typing it).
Type ‘//’ if you want to send a message with one ‘/’ in the beginning.


This command sends string to the server without a typing notification. This actually happens because the string gets typed in command−entry mode (‘/’). Note that there is a space after the first slash.

/send string

Send a raw command string to server.

/invite useraccount

Invite the user with account useraccount to join the switchboard session. You can also use the shortcut /i for this command. Example:

/spoof fake

Send a fake typing notification from user fake.

/file filename

Send a request to send the file filename.



Send a beep to others so that everybody pay attention.


Tell everybody you are using gtmess.

/msg text

Send a message to other gtmess users. The message appears on their notification window.

/dlg text

Send a message to other gtmess users. The message appears on their switchboard window.



redraw screen from scratch


produce a console beep


toggle display of offline contacts


mini help


display / hide the transfers window


messages window scroll down


messages window scroll up


toggle menu bar


exit the client

NOTE: You can emulate the function keys F1 to F10 by pressing ESC first and then a digit from ‘1’ to ‘0’. For instance, ESC−1 is equivalent to F1, ESC−2 is F2, ESC−0 is F10. ALT−<digit> might also work. To emulate Alt+F7 or Alt+F8 you can press ESC−& or ESC−* (or ALT−&, ALT−*).

When you are presented with an edit box to type a string, you can use the following keys:

move cursor left/right


move cursor to home/end


toggle insert mode


delete character at cursor and move the rest to the left


delete word


move one word left


move one word right


cut line to clipboard (same as ^K-X, see below)


delete character on the left


cancel editing (leaves string unmodified)


exit edit mode and save string

arrow UP/DOWN

recall previous/next line from history


enter escape mode

Escape mode is valid for exactly one keystroke and is automatically exited after it. Typical operations in this mode are clipboard operations. Invalid keystrokes exit the mode. You cannot cut or copy a masked field (i.e. password), though you can paste on it. The following are valid keystrokes in escape mode:


set block begin


copy whole line to clipboard buffer


copy from block begin to current position


paste buffer contents


cut line to buffer


clear (zap) line (without affecting the buffer)


push line into history and zap


insert newline (shown as "|")


toggle multi-line mode; in multi-line mode ENTER adds a newline character; the string will be accepted as soon as you turn off the mode (^K−ENTER again)


word left (to avoid conflicts with program ‘screen’)


word right


delete word

When you are presented with a list of contacts or groups, you can use the following keys (note that this contact/group selection is required by some functions and appears in the bottom line; do not confuse it with the contact list on the right that can also be used as a menu):
or arrow RIGHT/DOWN

next entry

[ or arrow LEFT/UP

previous entry

{ or HOME

first entry

} or END

last entry


show contact/group information




cancel selection

When the transfers window is visible, you can use the following keys:
or arrow DOWN

next entry

[ or arrow UP

previous entry

} or arrow RIGHT

scroll left

{ or arrow LEFT

scroll right


accept incoming invitation


reject incoming invitation


cancel (abort) incoming/outgoing transfer or outgoing invitation




delete entry


mini help

When a user is typing a message, a typing notification is usually sent by the user’s client. Not all clients are able to send or receive typing notifications. However, gtmess both sends and receives typing notifications. It is also able to do some kind of spoofing (see next section). When a typing notification is received, an exclamation mark (‘!’) is displayed on the left of the user’s name on the contact list. This means that the user is typing a message in some switchboard window. Although it is possible to know the specific s/b window, the current version does not distinguish between s/b windows. Hopefully this will be fixed in the future.


There are some features of the protocol that gtmess takes advantage of, while the original client for windows does not use them. These features are:


Get notified when somebody has opened a chat window to you (but has not sent a message yet).


Allow you to log in with a different initial status.

NOTE: If you log in as Appear Offline, other users will still receive some offline events, at least under protocol version MSNP12. Therefore, if you were offline in the first place, they can suspect that you have just logged in. Gtmess will detect this ‘fact’ and warn for a user possibly appearing offline (aka Invisible) ;)


Allow you to send a fake typing notification. This does not affect all clients. It used to affect older versions of the original client!


Allow you to know if somebody is online, but has blocked you. To find out if a user is blocking you do the following: Open a switchboard window and invite the user you think has blocked you (whom you see offline) to the session. If you receive an error 216, then the user has blocked you. Otherwise, if you receive an error 217 then we cannot tell. When you receive error 217 there are two cases: 1) The user is really offline and you can’t find out if he or she has blocked you. 2) The user appears offline and hasn’t blocked you.

To sum up, if a user is logged in and has blocked you, you will receive error 216.

NOTE: This feature was actually available due to a bug at the original messenger server. Nowadays the bug has been fixed, so block detection does not work any more. It is mentioned here for historic purposes.



Main configuration directory. This directory relies in the user’s home directory and stores the following gtmess−specific files:


The aliases file. It contains lines of the form email alias. Lines beginning with ‘#’ are considered to be comments, and therefore ignored. The alias export feature provides a convenient way to create an initial version of this file and then edit it manually.


The configuration file. It contains lines of the form variable=value. Lines beginning with ‘#’ are considered to be comments, and therefore ignored.


Received files from other users are stored in this directory.


The traffic log (see the log_traffic variable).


This file is a named pipe that is used by the gtmess−notify script to pop up notification windows. It is not used directly in this version of gtmess, you can safely remove it. ATTENTION: If the named pipe is not already open, an attempt to write to this file by a script through gtmess will block (unless the process that writes to the file runs in background)!


The directory where console logs are stored.


The file where per-contact settings are stored. Each line contains the contact email and its specific settings. The file is updated upon logout. Per-contact settings can be modified from the menu and only those contacts whose settings have been modified are stored.


Trusted root certificates, verified upon the initialization of an SSL connection. Gtmess first looks into the current directory for this file, then into ~/.gtmess/ and then into the default data prefix, usually /usr/local/share/gtmess.


This is the location of the sound effect files. Note that the prefix /usr/local/share/gtmess might be different in your system.


This is a list of known bugs and limitations.

If you send a file, you cannot see the IP of the receiver. When you receive a file, you cannot be server. When you send a file, you cannot be client.

There may occur conflicts in the authorization cookies of file transfers (though rare).

Messages are always assumed to be UTF−8 encoded.

When running ‘gtmess -h’, the default values shown for the scripts (*_exec) are overriden by the user configuration file.

You might get ‘socket read error’ when trying to log in. Retrying usually solves this problem.


gtmess−notify(1), gtmess_w(1), README file that comes along with the program; contains more up-to-date information, especially on the keyboard shortcuts


Operating System

Debian Linux, Mac OS X

Desktop Environment

WindowMaker, KDE 4, Quartz

Code Editor

NEdit, Qt Creator

Sound Effects


Audio Editor


Graphics Editor


File Manager

Midnight Commander


Credits go to the following people:

Mike Mintz for his excellent site on the MSN Messenger Protocol.

L. Peter Deutsch for his MD5 module.

Eric Rescorla for his article on SSL programming: R An introduction to OpenSSL Programming .

Qi Wenmin, kuuldor, David Lefevre for some useful patches they sent me.

Kosta Fliangos for kindly providing his FreeBSD box for testing.

The aMSN team for some useful ideas I got from their client.


Tibor Billes has corrected quite a few bugs and is also actively contributing code to the project.


gtmess − MSN Messenger client
Copyright (C) 2002−2010 George M. Tzoumas

This program 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 2 of the License, or (at your option) any later version.

This program 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 this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111−1307 USA