xboard(6)

NAME
xboard - X user interface for GNU Chess and the Internet Chess Server

SYNOPSIS
xboard [ options ]
xboard -ics [ options ]
xboard -ncp [ options ]

DESCRIPTION
xboard is a graphical chessboard that can serve as a user interface for GNU Chess or the Internet Chess Server, or can be used by itself.

As an interface to GNU Chess, xboard lets you play a game against the machine, set up arbitrary positions, force variations, or watch a game between two machines.

As an interface to the Internet Chess Server, xboard -ics lets you play against other ICS users, observe games they are playing, or review games that have recently finished.

You can also use xboard as a chessboard to play through games. It will read and write game files and allow you to play through variations manually. You can use it to keep track of email postal games, browse games off the net, or review GNU Chess and ICS games you have saved. These features are available at all times; even if you do not have access to GNU Chess or the ICS, you can use them by giving the command xboard -ncp.

After starting xboard, you make moves by dragging pieces with the mouse. Press mouse button 1 while the cursor is on one of your pieces, then move the cursor to another square and release the button.

OPTIONS
The following command line options correspond to X resources with the same names, so you can set them in your .Xdefaults file if you like. For options that have two names, the longer one is the name of the corresponding X resource.

To turn a boolean option on or off in your .Xdefaults file, give its long name followed by the value True or False. To turn a boolean option on or off from the command line, you can give its long name followed by the value True or False (-option True), or you can give just the short name to turn the option on (-opt), or the short name preceded by "x" to turn the option off (-xopt).

GNU Chess Options

-tc or -timeControl minutes[:seconds]
-mps or -movesPerSession moves
    Each player begins with the specified amount of time on his clock. If a player makes the specified number of moves before his clock runs out, xboard adds the specified amount of time to his clock. Default: 40 moves in 5 minutes.

-clock or -clockMode
    Determines whether or not to display the chess clocks. If clockMode is False, the clocks are not shown, but the side that is to play next is still highlighted. Also, unless searchTime or searchDepth is set, GNU Chess still keeps track of the clock time and uses it to determine how fast to make its moves.

-st or -searchTime minutes[:seconds]
    Tells GNU Chess to spend at most the given amount of time searching for each of its moves. Without this option, GNU Chess chooses its search time based on the number of moves and amount of time remaining until the next time control. Setting this option also sets clockMode to False.

-sd or -searchDepth number
    Tells GNU Chess to look ahead at most the given number of moves when searching for a move to make. Without this option, GNU Chess chooses its search depth based on the number of moves and amount of time remaining until the next time control. Setting this option also sets clockMode to False.

-mm or -matchMode
    Automatically runs a game between two chess programs. If the loadGameFile or loadPositionFile option is set, xboard will start the game with the given opening moves or the given position; otherwise, the game will start with the standard initial chess position. If the saveGameFile option is set, a move record for the match will be appended to the specified file. If the savePositionFile option is set, the final position reached in the match will be appended to the specified file. When the match is over, xboard will exit. Default: False.

-fcp or -firstChessProgram program
    Name of first chess program. In matches between two machines, this program plays black. Default: "gnuchessx".

-scp or -secondChessProgram program
    Name of second chess program, if needed. In matches between two machines, this program plays white; otherwise it is not started. Default: "gnuchessx".

-fh or -firstHost host
    Name of host the first chess program plays on. Default: "localhost".

-sh or -secondHost host
    Name of host the second chess program plays on. Default: "localhost".

-rsh or -remoteShell shell-name
    Some systems do not use rsh as the remote shell. This option allows a user to name the remote shell command.

-initString string
    The string that is sent to initialize the chess program. Default: "new\nbeep\nrandom\neasy\n". If you change this option, don't remove the "new" and "beep" commands. You can remove the "random" command if you like; including it causes GNU Chess to randomize its move selection slightly so that it doesn't play the same moves in every game. (Even without "random", GNU Chess randomizes its choice of moves from its opening book.) You can also remove "easy" if you like; including it toggles easy mode off, causing GNU Chess to think on your time. That is, if "easy" is included in the initString, GNU Chess thinks on your time; if not, it does not. (Yes, this does seem backwards, doesn't it!) To see what GNU Chess is thinking about, you can add the "post" command and run xboard with debugMode turned on. You can also try adding other commands to the initString; see the GNU Chess documentation for details.

-whiteString string
-blackString string
    These options control what is sent when the Machine White and Machine Black buttons are selected. This is mostly for compatibility with obsolete versions of GNU Chess.

Internet Chess Server Options

-ics or -internetChessServerMode
    Connect with an Internet Chess Server to play chess against its other users, observe games they are playing, or review games that have recently finished. Default: False. To use xboard in ICS mode, run it in the foreground, and use the terminal you started it from to type commands and receive text responses from the chess server. Useful ICS commands include who to see who is logged on, games to see what games are being played, match to challenge another player to a game, observe to observe an ongoing game, oldmoves to review a recently completed game, and of course help. Whenever you ask to observe an ongoing game, review a completed game, or resume an adjourned game, xboard retrieves and parses the list of past moves from the ICS, so you can review them with the Forward and Backward commands or save them with Save Game. You can create a script file containing ICS commands that xboard will type in for you whenever you connect to the ICS. See FILES below.

-autoflag or -autoCallFlag
    If autoCallFlag is True and your opponent runs out of time before you do, xboard will automatically call his flag, claiming a win on time (or a draw if you do not have mating material). Default: False.

-icshost or -internetChessServerHost host
    The Internet host name or address of the chess server to connect to when in ICS mode. Default: "coot.lcs.mit.edu". If your site doesn't have a working Internet name server, try specifying the host address in numeric form. The address for coot.lcs.mit.edu is "18.52.0.70" at this writing.

-icsport or -internetChessServerPort port-number
    The port number to use when connecting to a chess server in ICS mode. Default: 5000.

-gateway
    If this option is set to a host name, xboard uses rsh to run telnet on the given host to communicate with the Internet Chess Server instead of opening a direct TCP connection. This option is useful if your machine is unable to connect directly to the ICS but is able to rsh to a gateway host that can connect to the ICS. As an example, suppose the gateway host is called gate.wassamatta-u.edu, and you set options as follows:
        -gateway gate.wassamatta-u.edu
        -internetChessServer coot.lcs.mit.edu
        -internetChessServerPort 5000
    Then when you run xboard in ICS mode, it will connect to the ICS by using rsh to run the command "telnet coot.lcs.mit.edu 5000" on host gate.wassamatta-u.edu.

-telnet or -useTelnet
    If this option set to True, xboard runs the telnet(1) program to communicate with the Internet Chess Server instead of opening a direct TCP connection. The default is False. One case where this option is useful is if your machine is unable to connect directly to the ICS but is able to telnet to a gateway host that can connect to the ICS. It is more general than the gateway option, because you may be able to telnet to a host that you cannot rsh to, but it's not as convenient to use. As an example, suppose the gateway host is called gate.wassamatta-u.edu, and you set options as follows:
        -useTelnet true
        -internetChessServer gate.wassamatta-u.edu
        -internetChessServerPort 23
    Then when you run xboard in ICS mode, you will get a login prompt from the gateway host. Log in there and run the telnet program (giving a command like "telnet coot.lcs.mit.edu 5000") to connect to the ICS. This works because giving the option "-internetChessServerPort 23" causes xboard to connect to the gateway host's standard incoming telnet service instead of trying to connect to a chess server running on the gateway host.

-telnetProgram
    This option gives the name of the telnet program to be used with the gateway and useTelnet options. The default is "telnet". The telnet program is invoked with the value of internetChessServer as its first argument and the value of internetChessServerPort as its second argument.

Load and Save Options

-lgf or -loadGameFile file
-lgi or -loadGameIndex file
    If the loadGameFile option is set, xboard loads the specified position file at startup. If the loadGameIndex option is set to N, the Nth game found in the file is loaded; otherwise the first game is loaded.

-td or -timeDelay seconds
    Time delay between moves during "Load Game". Fractional seconds are allowed; try -td 0.4. A time delay value of -1 tells xboard not to step through game files automatically. Default: 1 second.

-sgf or -saveGameFile file
    If this option is set, xboard appends a record of every game played to the specified file.

-autosave or -autoSaveGames
    If this option is True, at the end of every game xboard prompts you for a filename and appends a record of the game to the file you specify. Ignored if autoSaveGames is set.

-lpf or -loadPositionFile file
-lpi or -loadPositionIndex file
    If the loadPositionFile option is set, xboard loads the specified position file at startup. If the loadPositionIndex option is set to N, the Nth position found in the file is loaded; otherwise the first position is loaded.

-spf or -savePositionFile file
    If this option is set, xboard appends the final position reached in every game played to the specified file.

User Interface Options

standard Xt options
    xboard accepts standard Xt options like -display, -geometry, and -iconic.

-bell or -ringBellAfterMoves
    If this option is True, xboard alerts you by ringing the terminal bell after each of your opponent's moves (or after every move if you are observing a game on the Internet Chess Server). The bell is not rung after moves you make or moves read from a saved game file. Default: False. If you turn on this option when using xboard with the Internet Chess Server, you will probably want to give the "set bell 0" command to the ICS, since otherwise the ICS will ring the bell itself after every move (not just yours).

-queen or -alwaysPromoteToQueen
    If this option is False (the default), xboard brings up a dialog box whenever you move a pawn to the last rank, asking what piece you want to promote it to. If the option is True, your pawns are always promoted to queens. (Your opponent can still underpromote, however.)

-size or -boardSize (Large | Medium | Small)
    Determines how large the board will be and what built-in piece bitmaps will be used. On a large board (the default), pieces are 80x80 pixels, on a medium board 64x64 pixels, and on a small board 40x40 pixels.

-coords or -showCoords
    If this option is True, xboard displays algebraic coordinates along the board's left and bottom edges. The default is False. The coordFont option specifies what font to use.

-flip or -flipView
    If you are playing a game on the ICS, the board is always oriented at the start of the game so that your pawns move from the bottom of the window towards the top. Otherwise, the starting is determined by the flipView option; if it is False (the default), White's pawns move from bottom to top at the start of each game; if it is True, Black's pawns move from bottom to top.

-title or -titleInWindow
    If this option is True, xboard displays player names (for ICS games) and game file names (for Load Game) inside its main window. If the option is False (the default), this information is displayed only in the window banner. You probably won't want to set this option unless the information is not showing up in the banner, as happens with a few X window managers.

-mono or -monoMode
    Determines whether xboard displays its pieces and squares with two colors (True) or four (False). You shouldn't have to specify monoMode; xboard will determine if it is necessary.

-borderXoffset
    -borderYoffset These options are part of a kludge that helps position the Comment and Edit Comment windows in the same place on the screen when they are closed and reopened. They should be set equal to the width and height of the borders that your X window manager adds to windows when it displays them. The defaults are correct for tvtwm(1).

-clockFont
    The font used for the clocks. If the option value is a pattern that does not specify the font size, xboard tries to choose an appropriate font for the board size being used. Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.

-coordFont
    The font used for rank and file coordinate labels if showCoords is True. If the option value is a pattern that does not specify the font size, xboard tries to choose an appropriate font for the board size being used. Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.

-font
    The font used for popup dialogs, menus, comments, etc. Default: -*-helvetica-medium-r-normal--*-100-*-*-*-*-*-*.

Alternate bitmaps for piece icons can be specified either by choosing one of the built-in sets or with the file name options described below. There are three built-in sets of piece bitmaps available, large (the default), medium, or small.

-solidPawnBitmap
-solidKnightBitmap
-solidBishopBitmap
-solidRookBitmap
-solidQueenBitmap
-solidKingBitmap
    Names of the bitmap files for the solid piece icons.
-outlinePawnBitmap
-outlineKnightBitmap
-outlineBishopBitmap
-outlineRookBitmap
-outlineQueenBitmap
-outlineKingBitmap
    Names of the bitmap files for the outline piece icons. These are used only in monochrome mode.

-whitePieceColor
    Color specification for white pieces, suitable for XParseColor(3X11). Default: #FFFFCC. These colors look good on a DEC workstation. If you need different colors, try using the xcolors application. Source for xcolors can be found in the X11 contrib directory.

-blackPieceColor
    Same for black pieces. Default: #202020.

-lightSquareColor
    Same for light squares. Default: #C8C365.

-darkSquareColor
    Same for dark squares. Default: #77A26D.

If you are using a grayscale monitor, try setting the colors to:
    -whitePieceColor     gray100
    -blackPieceColor     gray0
    -lightSquareColor    gray80
    -darkSquareColor     gray60

Other Options

-ncp or -noChessProgram
    If this option is True, xboard acts as a passive chessboard; it does not start a chess program at all. Turning on this option also turns off clockMode. Default: False.

-debug or -debugMode
    Turns on debugging printout.

MENU COMMANDS, BUTTONS, AND KEYS
All xboard commands are available on menus. The most frequently used commands also have shortcut keys or on-screen buttons.

File Menu

Reset
    Resets xboard and GNU Chess to the beginning of a new chess game. If you were playing or observing a game on the Internet Chess Server that is not finished yet, you will also need to enter an appropriate command to end your participation (for example, "resign" or "observe").

Load Game
    Plays a game from a record file. A popup dialog prompts you for the filename. If the file contains more than one game, and you want to load the Nth one, type the number N after the filename, separated by a space. The "g" key is a keyboard equivalent. The game file parser will accept almost any file that contains moves in algebraic notation. If the file includes an xboard position diagram bracketed by "[--" and "--]" before the first move, the game starts from that position. Text enclosed in parentheses or square brackets is assumed to be commentary and is displayed in a pop-up window. Any other text in the file is ignored.

Load Next Game
    Loads the next game from the last game record file you loaded.

Load Previous Game
    Loads the previous game from the last game record file you loaded.

Reload Same Game
    Reloads the last game you loaded.

Load Position
    Sets up a position from a position file. A popup dialog prompts you for the filename. If the file contains more than one saved position, and you want to load the Nth one, type the number N after the filename, separated by a space. Position files must be in the format that the Save Position command writes.

Save Game
    Appends a record of the current game to a file. A popup dialog prompts you for the filename. If the game did not begin with the standard starting position, the game file includes the starting position used. Game files are human-readable, and can also be read back by the Load Game command.

Save Position
    Appends a diagram of the current position to a file. A popup dialog prompts you for the filename. Position files are human-readable, and can also be read back by the Load Position command.

Exit
    Exits from xboard. The "q" key is a keyboard equivalent.

Mode Menu

Machine White
    Forces GNU Chess to play white. GNU Chess mode only.

Machine Black
    Forces GNU Chess to play black. GNU Chess mode only.

Two Machines
    Plays a game between two computer programs. GNU Chess mode only.

ICS Client
    ICS mode only. Takes xboard out of the Force Moves or Edit Position state.

Force Moves
    Forces a series of moves. That is, xboard allows you to make moves for both black and white. In GNU Chess mode, GNU chess continues to check moves for legality but does not participate in the game. The clocks do not run.

Edit Position
    Lets you set up an arbitrary board position. Use mouse button 1 to drag pieces to new squares, or to delete a piece by dragging it off the board or dragging an empty square on top of it. To drop a new piece on a square, press mouse button 2 or 3 over the square. This brings up a menu of white pieces (button 2) or black pieces (button 3). Additional menu choices let you empty the square or clear the board. You can set the side to play next by clicking on the White or Black indicator at the top of the screen.

Pause
    Pauses updates to the board, and if you are playing against GNU Chess, also pauses your clock. To continue, select Pause again, then select Forward to End if you want to immediately update the display to the latest position. The [P] button and keyboard "p" key are equivalents. If you select Pause when you are playing against GNU Chess and it is not your move, GNU Chess's clock will continue to run and it will eventually make a move, at which point both clocks will stop. Since board updates are paused, however, you will not see the move until you select Forward. This behavior is meant to simulate adjournment with a sealed move.

Edit Comment
    Adds or modifies a comment on the current position. Comments are saved by Save Game and are displayed by Load Game, Forward, and Backward.

Action Menu (ICS mode only)

Call Flag
    Calls your opponent's flag, claiming a win on time, or claiming a draw if you are both out of time. You can also call your opponent's flag by clicking on his clock.

Draw
    Offers a draw to your opponent, accepts a pending draw offer from your opponent, or claims a draw by repetition or the 50-move rule, as appropriate.

Decline Draw
    Declines a pending draw offer from your opponent.

Abort
    Asks your opponent to agree to aborting the current game, or agrees to a pending abort offer from your opponent. An aborted game ends immediately without affecting either player's rating.

Decline Abort
    Declines a pending abort request from your opponent.

Adjourn
    Asks your opponent to agree to adjourning the current game, or agrees to a pending adjournment offer from your opponent. An adjourned game can be continued later using the ICS "load" command.

Decline Adjourn
    Declines a pending adjournment request from your opponent.

Resign
    Resigns the game to your opponent.

Step Menu

Backward
    Steps backward through a series of remembered moves. The [<] button and the "b" key are equivalents. Backward normally only reviews old positions; it does not retract moves. If you are playing against GNU Chess and want to change your last move, you must use Force Moves mode to do so. Wait until it is your turn, select Force Moves, select Backward twice, make a different move, and then select Machine White or Machine Black to get GNU Chess back into the game.

Forward
    Steps forward through a series of remembered moves or through a game file. The [>] button and the f key are equivalents.

Back to Start
    Jumps backward to the first remembered position in the game. The [<<] button and the shifted "B" key are equivalents.

Forward to End
    Jumps forward to the last remembered position in the game. The [>>] button and the shifted "F" key are equivalents.

Options Menu

Always Queen
    Toggles the alwaysPromoteToQueen option.

Autoflag
    Toggles the autoCallFlag option.

Autosave
    Toggles the autoSaveGames option. Disabled if the saveGameFile option is set, as in that case all games are saved to the specified file.

Bell
    Toggles the ringBellAfterMoves option.

Flip View
    Inverts your view of the chess board for the duration of the current game. Starting a new game returns the board to normal. (If you are playing a game on the ICS, the board is always oriented at the start of the game so that your pawns move from the bottom of the window towards the top. Otherwise, the starting is determined by the flipView command line option; if it is False (the default), White's pawns move from bottom to top at the start of each game; if it is True, Black's pawns move from bottom to top.)

Show Coords
    Toggles the showCoords option.

Help Menu

Hint
    Displays a move hint from GNU Chess. GNU Chess mode only.

About
    Shows the current xboard version number.

Not on Menus

Iconify
    I, i, C or c iconifies xboard.

ENVIRONMENT
Game and position files are found in the directory named by the CHESSDIR environment variable. If this variable is not set, the current working directory is used. If CHESSDIR is set, xboard actually changes its working directory to $CHESSDIR, so GNU Chess listing files will be stored there as well.

FILES
Whenever xboard connects to the Internet Chess Server, if it finds a file called ".icsrc", it feeds the file's contents to the ICS as commands. Usually the first two lines of the file should be your ICS user name and password. The .icsrc file can be either in $CHESSDIR, in xboard's working directory if CHESSDIR is not set, or in your home directory.

SEE ALSO
gnuchess(6)

LIMITATIONS
There is no way for two people running copies of xboard to play each other without going through the Internet Chess Server.

The game parser recognizes only algebraic notation.

The internal move legality tester does not look at the game history, so in some cases it misses illegal castling or en passant captures. However, if you attempt such a move when using gnuchess (or the ICS), it will reject the move, and xboard will undo it and let you try another.

In ICS mode, xboard cannot handle observing (and/or playing) more than one game at a time. It may get confused if you try to do this, though it tries to recover gracefully. Use the Reset button and the ICS refresh command if you have problems.

Your password gets echoed when you log on to the ICS. This happens because xboard does not implement the telnet protocol. Also, if useTelnet mode is set, every line you type to the ICS gets echoed an extra time. This happens because xboard does not put the keyboard into raw mode and let the telnet program do all the echoing. (The details of how to do so vary on different systems.)

The .icsrc file does not work properly when you connect to ICS through a Unix gateway host with useTelnet mode. The Unix login process apparently discards type-ahead.

Some xboard functions may not work with versions of GNU Chess earlier than 4.0, patchlevel 52. In particular, with GNU Chess 3.1 the timeControl option can be given only to the nearest minute, restoring a saved position with black to play may not work, and if you use the Backward button after a mate or draw, the clocks are reset (because GNU Chess has exited and must be restarted).

AUTHORS
Original authors: Chris Sears and Dan Sears.

Enhancements, current maintainer: Tim Mann.

Thanks to John Chanak for the initial implementation of ICS mode.

COPYRIGHT
Copyright 1991 by Digital Equipment Corporation, Maynard, Massachusetts. Enhancements Copyright 1992-93 Free Software Foundation, Inc.

XBoard borrows its colors, icon and piece bitmaps from XChess, which was written and is copyrighted by Wayne Christopher.

The following terms apply to Digital Equipment Corporation's copyright interest in XBoard:

    All Rights Reserved

    Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Digital not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

    DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The following terms apply to the enhanced version of XBoard distributed by the Free Software Foundation:

    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., 675 Mass Ave, Cambridge, MA 02139, USA.