Protect against overrun of input buffer
[uci2wb.git] / uci2wb.pod
1 =head1 NAME
2
3 uci2wb - Protocol adapter for UCI dialects to XBoard
4
5
6 =head1 SYNOPSIS
7
8 B<uci2wb> [debug] [-var <variant>] [-nice <priority>] [-kill <delay>] [-c|-s|-x] engine [directory]
9
10
11 =head1 DESCRIPTION
12
13 B<uci2wb> is a protocol adapter, i.e. it can be used to run AI plugins ('engines')
14 that communicate in one protocol in a GUI that communicates in another.
15 In this case uci2wb can make appear the engine specified in its argument,
16 which must use a protocol similar to UCI ('Universal Chess Interface'),
17 to the GUI as an engine using XBoard protocol
18 ('Chess Engine Communication Protocol', CECP).
19
20 The protocols for which it can mediate are UCI
21 (both the official standard, as well as the 'Cyclone dialect' that is commonly used
22 by Chinese-Chess engines, and the 'Arena960 dialect' used by pre-standard Chess960 engines),
23 USI ('Universal Shogi Interface', used by some Shogi engines)
24 and UCCI ('Universal Chinese-Chess Interface').
25 When set to UCI, it automatically uses Cyclone dialect when playing xiangqi games.
26
27
28 =head1 OPTIONS
29
30 =over 8
31
32 =item B<-c -s -x -f>
33
34 The flag arguments B<-c> (default), B<-s> or B<-x> set uci2wb to use UCI, USI or UCCI, respectively.
35 If there is more than one character in the flag argument,
36 all characters but the first are ignored.
37 This can be used by passing uci2wb the full variant name ('shogi' or 'xiangqi') as a flag,
38 to make it automatically choose the appropriate protocol (USI or UCCI).
39 Other values also select UCI, but the value B<-f> in addition implies uci2wb should announce
40 it supports Chess960 even for UCI engines that don't have the standard UCI_Chess960 option,
41 and in that case causes castlings to be sent to them as O-O or O-O-O
42 instead of the standard KxR notation.
43
44 =item B<-var <variant>>
45
46 Forces uci2wb to announce to the GUI it supports (only) the specified variant.
47 Although a UCI_Variant option has been proposed as a way for UxI engines to announce what they can play,
48 (and is supported by uci2wb), not many engines implement this.
49 So if these are not the standard variants implied by the protocol choice,
50 (but, f.e. seirawan or 6x6+6_shogi) it has to be configured on the
51 uci2wb command line through this option.
52
53 =item B<-nice <priority>>
54
55 Runs the engine processes at the requested priority;
56 positive values lower the priority.
57
58 =item B<-kill <delay>>
59
60 Increases the time between receiving a 'quit' command and killing of an engine process
61 that somehow could not be made to exit through the normal handling of this (50 ms by default)
62 by the specified delay.
63
64 =item B<debug>
65
66 Makes uci2wb report to the GUI everything it receives from the engine,
67 as a CECP engine comment (i.e. prefixed with '#').
68 This would make it appear in the GUI's log of the engine communication.
69 Some critical commands it sends to the engine
70 (such as the 'position-moves' and 'go' commands)
71 will be reported as well.
72 This option can also be switched interactively,
73 through the 'UCI2WB debug output' checkbox option appearing
74 as additional engine option.
75
76 =item B<directory>
77
78 If a directory is specified, the engine is started
79 with that directory set as current directory.
80
81 =item B<byoyomi work-arounds>
82
83 Byoyomi is a mode of time control in USI not supported by CECP.
84 Engines can be forced to run in this mode by letting the GUI use
85 incremental or sudden-death TC,
86 and ticking the interactive 'Floating Byoyomi' checkbox option
87 that uci2wb pools with the engine options.
88 An accompanying option 'Byoyomi (sec)' allows you to force a fixed
89 value >= 0 for the byoyomi to be sent to the engine
90 when 'Floating Byoyomi' is off.
91
92 =back
93
94 =head1 AVAILABILITY
95
96 At http://hgm.nubati.net/cgi-bin/gitweb.cgi the source code can be obtained.
97
98 =head1 SEE ALSO
99
100 xboard(6)
101
102 =head1 STANDARDS
103
104 WinBoard, B<xboard>(6) interface ("Chess Engine Communication Protocol")
105
106 UCI specs: http://www.shredderchess.com/chess-info/features/uci-universal-chess-interface.html
107
108 USI specs: http://hgm.nubati.net/usi.html
109
110 UCCI specs: http://www.xqbase.com/protocol/cchess_ucci.htm
111
112 =head1 AUTHOR
113
114 H.G.Muller <h.g.muller@hccnet.nl>.
115
116 This manual page was generated with pod2man(1).