1 .TH sympathy 1 "%VERSIONSTAMP%" "%LONGVERSION%" "USER COMMANDS"
3 sympathy \- client/server terminal emulator with logging
7 .B \fIterminal_options\fP
9 .B \fIdisplay_options\fP
14 .B \fIterminal_options\fP
16 .B \fIserver_options\fP
21 .B \-\fBc\fP \-\fBs\fP
23 .B \fIterminal_options\fP
25 .B \fIserver_options\fP
27 .B \fIclient_options\fP
32 .B \fIclient_options\fP
38 .B \fIclient_options\fP
43 .\" "sympathy -t [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u]\n"
44 .\" "sympathy -s [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n"
45 .\" " [-n hlines] [-w WxH] [-F]\n"
46 .\" "sympathy [-s -c] [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n"
47 .\" " [-n hlines] [-w WxH]\n"
48 .\" "sympathy -c [-H] [-u] -k skt\n"
49 .\" "sympathy -r id [-H] [-u]\n"
50 .\" "sympathy {-l|-ls}\n"
56 is a VT52/VT100/ANSI terminal emulator with some special features. In normal use
58 would sit between a terminal device (a serial port or a ptty) and
59 the user's usual terminal emaulator (eg xterm(1)).
61 renders data from the terminal device into an internal frame buffer
62 and then expresses changes in this frame buffer to the outer terminal
63 emulator using a small subset of ANSI escape codes.
65 always generates valid escape codes to the outer terminal, and will
66 reset the state of its internal terminal emulator when it detects
67 framing errors on the terminal device.
70 unlike screen(1), takes care to preserve the scrollback features
71 of the outer terminal emulator: lines that scroll of the top of the internal
72 frame buffer are scrolled off the top of the outer terminal emaultor. When
73 sympathy is used in client/server mode, some history is added to the outer
74 terminal emulator when the client connects.
77 also supports automatic baud rate detection, and advanced logging features.
79 logs whenever any of the modem control lines change state, receive errors,
81 of any line on the frame buffer as the cursor moves off it.
83 .B \fImajor mode options\fP:
86 act as terminal emulator only:
88 opens the terminal device and outputs into the outer terminal emulator, when sympathy exits the
89 device is closed and no process remains. In this mode sympathy behaves like a traditional
90 terminal emulator such as cu(1) or minicom(1).
95 opens the terminal device and renders into an internal frame buffer, listens for clients
96 on the socket and logs activity. By default the server will fork into a daemon processes
97 but can be forced to remain in the forground with the \-\fBF\fP option.
99 .B \-c\fP or \fB\-r\fP \fIid\fP
102 connects to a sympathy server process and injects the history into the outer terminal
104 and connects the user with the terminal device. One server process can support multiple
105 client processes. This mode can also be used to obtain a dump of the current screen
106 in HTML format (see the \-\fBH\fP option). The \-\fPr\fP option connects to a server
107 on the socket ~/.sympathy/\fIid\fP or if \fIid\fP is an integer
108 ~/.sympathy/\fIhostname\fP.\fIid\fP mimicking the behaviour of screen(1). With the
109 \-\fBc\fP option the socket must be specified with the \-\fBk\fP option.
111 .B \fP[\fB \-c \-s \fP]
112 act as both client and server:
114 forks. The child process becomes a server, and the orginal process becomes a client
115 which then connects to the server. This is the default major mode if no other is specified.
116 Since the default terminal device is a ptty, running
118 with no arguments will start a new shell in a daemonized process and connect to it
119 as a client from the original process, mimicking the behaviour of screen(1)
124 will show active sockets, ones to which a call to connect(2) succeeds,
125 in ~/.sympathy. If the socket name begins with the hostname of the machine, and
126 the call to connect(2) fails, then socket will be unlinked.
129 show current version:
131 will print the the version number of the code it was compiled with.
136 will show brief usage instructions
138 .B \fIterminal_options\fP:
140 .B \-d \fIserialdev\fP
141 connect to terminal device \fIserialdev\fP, eg /dev/ttyS0.
145 lock the terminal device, but checks periodically for lock files of other processes. If
146 sympathy detects another lock file it displays \fBLocked\fP in the status line
147 and refuses I/O on the device until the lock file is removed or becomes invalid.
148 To lock the device use the \-\fBK\fP option.
150 will in addition check that the name of the device does not occur in /proc/cmdline
151 as an argument to the \fIconsole\fP kernel parameter.
152 The \-\fBd\fP option is incompatible with the \-\fBp\fP option.
155 connect to a pseudo-tty instead of a terminal device, and fork a login shell in
156 it. The \-\fBp\fP option is incompatible with the \-\fBd\fP option. This is the default
157 terminal device if none is specified.
160 lock the terminal device specificed in the \-\fBd\fP option.
162 generates lock files in a staggering variety of formats and places. For locks
163 based on the name of the device sympathy generates lock files for all devices
164 with the same major and minor in /dev, /dev/usb and /dev/tts, it uses both normal
165 and lower case and replaces occurances of '/' in the device name with both '.' and '_'.
167 also generates locks based on the device major and minor numbers, and for all lock file
168 names generates them in any of the follwoing directories that are writable:
169 /var/lock/uucp, /var/spool/lock, /var/spool/uucp, /etc/locks, /usr/spool/uucp,
170 /var/spool/locks, /usr/spool/lock, /usr/spool/locks, /usr/spool/uucp/LCK, /var/lock.
171 Lock files are assumed to be in HDB format.
173 .B \-b \fIbaudrate\fP
174 set the baud rate of the terminal device specificed in the \-\fBd\fP to baudrate, if omitted
175 the current baudrate of the serial port will be used.
178 turn on flow control on the terminal device. This option adds \fICRTSCTS\fP to sympathy's default
179 \fIc_cflag\fPs of \fICS8|CREAD|CLOCAL\fP.
182 log activity to the file \fIlogfile\fP. If \fIlogfile\fP is '-' then log to \fIstdout\fP. Note
183 that logging to \fIstdout\fP only makes sense with the \-\fBF\fP \fIserver_option\fP.
185 .B \-w \fIwidth\fP[x\fIheight\fP]
186 set the initalize size of the terminal emulator's frame buffer to be \fIwidth\fP columns
187 by \fIheight\fP rows. If \fIheight\fP is ommited it defaults to 24, the default width
188 is 80. These values may
189 be overridden later by terminal escape sequences. If \-\fBp\fP is also specificed
190 the ptty will have its window size set to match.
192 .B \fIdisplay_options\fP:
195 attempt to render unicode characters in the internal frame buffer to the outer terminal
196 emulator by using ISO-2202 sequences.
198 currently only checks to see if an appropriate character appears in the VT102
199 US character set, or in the VT102 'special characters and line drawing' character set.
200 If the character appears in neither of these then it will be rendered on the outer
201 terminal emulator as a '?'.
204 render the current state of the internal frame buffer to stdout as HTML, then quit.
206 .B \fIclient_options\fP:
209 set the name in the filesystem of the socket to which
211 should connect. This option is \fBmanditory\fP unless the \-\fBs\fP or \-\fBr\fP options
212 have also been given. If \-\fBs\fP is given then it will default to the socket which
213 the forked server process opens. See the discusion of the \-\fPr\fP option above, for
216 chooses a socket name if \-\fBr\fP is specified.
218 .B \fIserver_options\fP:
221 set the name in the filesystem of the socket on which
223 should listen for clients. If this option is omitted
226 socket in ~/.sympathy, creating that directory if neccessary, and named
227 \fIhostname\fP.\fIpid\fP where \fIpid\fP is the process id of the
229 process that created the socket.
234 server process not to become a daemon but to remain the the foreground. This option is
235 incompatible with the \-\fBc\fP \-\fBs\fP major mode.
238 sets the number of lines of history that the server process stores to \fInlines\fP. When
239 a client connects \fInlines\fP of history are injected into the outer terminal emulator
240 so that they can be seen when scrolling back. By default the server stores 200 lines of
245 is relaying data to the outer terminal emulator a reverse video status line
246 will be visible at the bottom of the screen. The status line shows pertinent
247 information. The first item on the line reminds you what the current escape character
248 is, the second indicates the terminal device to which
250 is connected, and the third shows the current baudrate. Other messages are:
253 indicates that that RTS/CTS flow control is in operation on the terminal device.
256 indicates that the terminal device is asserting the RTS line which indicates that
257 the local system is ready to accept data from the remote system. If RTS/CTS
258 flow control is in operation then the operating system or hardware may
259 de-assert RTS even if RTS is shown. See the section on SERIAL PORT THEORY for
263 indicates that the terminal device has detected that the local system's CTS
264 line is being asserted, indicating that the remote system is ready to receive
265 data from the local system. See the section on SERIAL PORT THEORY for
269 indicates that the terminal device is asserting the DTR line indicating that the local
270 system would like the local DCE to establish a connection to the remote
271 DCE. See the section on SERIAL PORT THEORY for more information.
274 indicates that the terminal device has detected that the local system's DSR line is
275 being asserted, indicating that the local DCE is ready. See the section on
276 SERIAL PORT THEORY for more information.
279 indicates that the terminal device has detected that the local system's CD line is
280 being asserted, indicating that the local DCE has a connection to the remote DCE.
281 See the section on SERIAL PORT THEORY for more information.
284 indicates that the terminal device has detected that the local system's RI line is
285 being asserted, indicating that the DCE has detected a ringing signal or incoming
289 shows the number of connected client processes. In the \-\fBt\fP major mode, this will
293 the terminal device was opened without the \-\fbK\fP flag and another process is
294 currently using it. I/O to the device is currently suspended until the process dies
295 or removes its lock file.
298 indicates the number of frames recived by the terminal device with errors (indicating
299 the wrong parity, baud rate or framing). The count resets if no errors are
300 detected by the device for 10 seconds.
304 thinks that you have set the wrong baud rate and is unable to determine the correct
305 one as the current baud rate is lower than the correct baud rate. Use the \fBbaud\fP command
306 to set a higher baud rate (eg 115200) and sympathy will try again.
310 thinks that you have set the wrong baud rate and thinks that the correct baud rate is
311 \fIrate\fP. Use the \fBbaud\fP command to change the current baud rate.
313 Commands are entered by sending the escape character, ascii(7) STX, from the outer terminal
314 emulator (usally by pressing CTRL\-B), typing the comamnd and pressing return. Whilst the
315 command is entered the status line changes to ':' and rudementary line editing is available.
316 Whilst the command is entered the cursor \fBdoes not move\fP but remains where the terminal
317 emulator has placed it. Valid commands are:
320 switch from vt102 behaviour to ansi behaviour. The most noticabel difference is
321 the so called 'xn' glitch.
324 switch from ansi behaviour to vt102 behaviour.
327 set the current baud rate to nnnn
330 send the break signal by asserting the TX line for longer than a frame period.
333 enable RTS/CTS flow control
336 disable RTS/CTS flow control
339 deassert DTR for one second.
342 exit this instance of sympathy (disconnect from the server if present)
343 .SH CHARACTER ENCODINGS
344 For characters between 32 and 126
346 interprets them as would a VT102 terminal by following the subset of ISO-2202 that
347 the VT102 supports. Characters 128 thru 255 are assumed to be in UTF-8(7), if
348 however the UTF-8 is invalid they will instead be interpreted as characters
349 from ISO_8859-1(7). Character 155 (0x9b) when not part of a valid UTF-8 sequence
350 will be interpreted as the one byte CSI character.
352 For the outer terminal emulator sympathy by default issues the
353 ESC % G sequence to select UTF-8 mode and emits valid UTF-8. If the outer terminal
354 does not, however, support UTF-8 use the \-\fBu\fI switch to force
356 to use the VT102 subset of ISO-2202.
358 Log files are made exclusively in the UTF-8 encoding. Each line in the log file
359 starts with the date and time at which the entry was made \- for example:
361 Feb 27 23:24:42.509440
364 logs a line to the file whenever the cursor leaves the line. Additionally sympathy
365 logs certain other events to the file when the baud rate is changed
367 writes <baud changed to 19200>. Whenever a modem control line changes state
369 appends <Modem lines changed: \fI+/-line\fP> to the log. Where \fI+\fP
370 indicates that \fIline\fP was asserted and \fI-\fP indicates that it was de-asserted.
371 When the terminal device reports receive errors
373 adds aditional information to the log. It reports the character sequence reporting the error
375 <tty reports error: \\377 \\000 \\000>
377 the observed frequencies of the different bit periods
379 <tty_bit_analyse: 0000000001 [0,0,0,0,0,0,110,0,0,80]>
381 and the conclusions of the baud rate guessing algorythm
383 <tty_analyse: 80 errors, current rate 115200b, suggest 19200b>
385 Invalid utf-8 srequences are also reported
387 <invalid utf-8 sequence: \\301>
391 .I sympathy uses the \fBHOME\fI environment variable to determine the default
392 location for sockets. .br
393 .I sympathy sets the value of \fBTERM\fI in pseudo-ttys spawned using the
394 \-\fBp\fP argument to 'xterm'
397 completely emulates a VT102 terminal (including the VT52 emulation).
399 also emulates a few extra sequences: the xterm(1) CSI ] ... sequences, and
400 the ANSI CSI @ and CSI b sequences. The numeric keypad follows exactly the
401 sequences produced by an xterm rather than the exact VT102/VT220 sequences.
403 also recognises the ESC % G and the ESC % @ sequnces to switch between ISO-2202
404 and UTF-8 but ignores them (see CHARACTER ENCODING below)
405 .SH SERIAL PORT THEORY
406 A serial connexion was originally invisaged to connect a DTE (Data Terminal Eqipment)
407 to a DCE (Data Circuit-terminating Equipment). The DCE (some sort of modem) would assert
408 the DTE's (the computer or terminal) DSR line to indicate it was ready. The DTE would
409 assert DTR to indicate to the DCE that it should attempt a connexion to the remote DCE.
410 Once a connexion was established the DCE would assert the DTE's CD pin. Data could then
411 flow between the DTR and the remote DTE via the two DCEs. Flow control was provided
412 via the RTS CTS lines. The DTE asserts RTS when it is capable of receiving new data,
413 and pasues its transmission of data when the CTS line is de-asserted. The local DCE
414 asserts CTS when the remote DCE detects RTS, and vice versa.
416 In modern usage the signals are slightly different, for a typical connexion using modems
417 DSR indicates that the modem is ready, a drop DTR is used to indicate to the
418 modem that it should break the connexion to the remote modem. CD indicates that
419 the local modem is connected to the remote modem, and CTS and RTS behave as before. Connexion
420 is established by in-band signalling before CD is asserted.
422 For a \fBnull modem\fP cable local DSR and DTR are wired to remote CD, local
423 CTS to remote RTS, and local RTS to remote CTS. Thus asserting local DTR
424 asserts local DSR and remote CD, and asserting local RTS asserts remote CTS.
426 When RTS/CTS flow control is in operation the operating system or the hardware
427 de-asserts RTS when its buffer becomes full causing (via the DCEs or the null
428 modem cable) a de-assertion of remote CTS which causes the remote to cease transmission.
431 using sympathy to mimmick screen(1):
433 [foo@barhost ~]$ sympathy
436 forks. The child becomes a daemon server and launches a new shell in a
437 pseudo-tty, the original process becomes a client and connects to the server
438 and shows the output. The user then uses the new shell and after some time
439 either hangs up on the client or issues CTRL\-B quit, and the client detaches from
442 Later the user wishes to retreive her session and to determine which sympathy
443 sessions are active issues:
445 [foo@barhost ~]$ sympathy \-ls
447 barhost.2456 (Active)
451 The user then issues:
453 [foo@barhost ~]$ sympathy \-r 2456
455 and is reconnected to her session.
457 using sympathy to mimick minicom(1):
460 [foo@barhost ~]$ sympathy -t -d /dev/modem -b 9600 -K
463 opens the device /dev/modem and locks it, sets the baud rate to 9600 baud and disables
464 flow control. A VT102 terminal emulator then displays the data from the modem. The user
465 quits the emulator by issuing CTRL\-B quit, which unlocks the modem and exits sympathy.
467 using sympathy to mimick consolidate(1):
470 [foo@barhost ~]$ sympathy -s -d /dev/ttyS13 -b 19200 -K -k /root/sympathy/13 -L /root/sympathy/13.log
473 becomes a daemon and detaches from the current tty. It then opens the device
474 /dev/ttyS13 and locks it, sets the baud rate to 19200 baud and disables flow
477 then listens for clients connecting on the socket -fI/root/sympathy/13-fP, whilst logging
478 completed lines and changes in status to the file /root/sympathy/13.log.
480 A user wishing to see the current status of the /dev/ttyS13 issues:
482 [foo@barhost ~]$ sympathy -c -k /root/sympathy/13
484 and the last 200 lines of history are injected into the history of her outer
485 terminal emulator and she is connected to /dev/ttyS13.
489 screen(1) minicom(1) consolidate(1)
494 the command line editor should support better line editing and report failed commands
496 when the \-\fBc\fP \-\fBs\fP major mode is used without the \-\fBk\fP option the pid
497 used in the socket is that of the client process and therefore not unique.
499 the HTML generated with the \-\fBH\fP option is ugly.
501 no useful error message is generated if opening the terminal device fails in the
502 \-\fBc\fP \-\fBs\fP major mode.
504 James McKenzie, james@fishsoup.dhs.org