.TP 5
.B \-p
connect to a pseudo-tty instead of a terminal device, and fork a login shell in
-it. The \-\fBd\fP option is incompatible with the \-\fBd\fP option. This is the default
+it. The \-\fBp\fP option is incompatible with the \-\fBd\fP option. This is the default
terminal device if none is specified.
.TP 5
.B \-K
the current baudrate of the serial port will be used.
.TP 5
.B \-f
-turn on flow control on the terminal device. This option add \fICRTSCTS\fP to sympathy's default
+turn on flow control on the terminal device. This option adds \fICRTSCTS\fP to sympathy's default
\fIc_cflag\fPs of \fICS8|CREAD|CLOCAL\fP.
.TP 5
.B \-L \fIlogfile\fP
.I Sympathy
thinks that you have set the wrong baud rate and thinks that the correct baud rate is
\fIrate\fP. Use the \fBbaud\fP command to change the current baud rate.
-
+.SH COMMANDS
+Commands are entered by sending the escape character, ascii(7) STX, from the outer terminal
+emulator (usally by pressing CTRL\-B), typing the comamnd and pressing return. Whilst the
+command is entered the status line changes to ':' and rudementary line editing is available.
+Whilst the command is entered the cursor \fBdoes not move\fP but remains where the terminal
+emulator has placed it. Valid commands are:
+.TP 5
+.B ansi
+switch from vt102 behaviour to ansi behaviour. The most noticabel difference is
+the so called 'xn' glitch.
+.TP 5
+.B noansi
+switch from ansi behaviour to vt102 behaviour.
+.TP 5
+.B baud \fInnnn\fB
+set the current baud rate to nnnn
+.TP 5
+.B break \fInnnn\fB
+send the break signal by asserting the TX line for longer than a frame period.
+.TP 5
+.B flow
+enable RTS/CTS flow control
+.TP 5
+.B noflow
+disable RTS/CTS flow control
+.TP 5
+.B hangup
+deassert DTR for one second.
+.TP 5
+.B quit
+exit this instance of sympathy (disconnect from the server if present)
+.SH CHARACTER ENCODINGS
+For characters between 32 and 126
+.I sympathy
+interprets them as would a VT102 terminal by following the subset of ISO-2202 that
+the VT102 supports. Characters 128 thru 255 are assumed to be in UTF-8(7), if
+however the UTF-8 is invalid they will instead be interpreted as characters
+from ISO_8859-1(7). Character 155 (0x9b) when not part of a valid UTF-8 sequence
+will be interpreted as the one byte CSI character.
.PP
- you can send commands by sending
-ascii(7) STX from the outer terminal emulator (usally by pressing CTRL-B).
-
-the s
+For the outer terminal emulator sympathy by default issues the
+ESC % G sequence to select UTF-8 mode and emits valid UTF-8. If the outer terminal
+does not, however, support UTF-8 use the \-\fBu\fI switch to force
+.I sympathy
+to use the VT102 subset of ISO-2202.
.SH LOG FILES
+Log files are made exclusively in the UTF-8 encoding. Each line in the log file
+starts with the date and time at which the entry was made \- for example:
+.br
+Feb 27 23:24:42.509440
+.br
+.I Sympathy
+logs a line to the file whenever the cursor leaves the line. Additionally sympathy
+logs certain other events to the file when the baud rate is changed
+.I sympathy
+writes <baud changed to 19200>. Whenever a modem control line changes state
+.I sympathy
+appends <Modem lines changed: \fI+/-line\fP> to the log. Where \fI+\fP
+indicates that \fIline\fP was asserted and \fI-\fP indicates that it was de-asserted.
+When the terminal device reports receive errors
+.I sympathy
+adds aditional information to the log. It reports the character sequence reporting the error
+.IP
+<tty reports error: \\377 \\000 \\000>
+.PP
+the observed frequencies of the different bit periods
+.IP
+<tty_bit_analyse: 0000000001 [0,0,0,0,0,0,110,0,0,80]>
+.PP
+and the conclusions of the baud rate guessing algorythm
+.IP
+<tty_analyse: 80 errors, current rate 115200b, suggest 19200b>
+.PP
+Invalid utf-8 srequences are also reported
+.IP
+<invalid utf-8 sequence: \\301>
.SH EXIT STATUS
+FIXME
.SH ENVIRONMENT
+.I sympathy uses the \fBHOME\fI environment variable to determine the default
+location for sockets. .br
+.I sympathy sets the value of \fBTERM\fI in pseudo-ttys spawned using the
+\-\fBp\fP argument to 'xterm'
+.SH EMULATION
+.I Sympathy
+completely emulates a VT102 terminal (including the VT52 emulation).
+.I Sympathy
+also emulates a few extra sequences: the xterm(1) CSI ] ... sequences, and
+the ANSI CSI @ and CSI b sequences. The numeric keypad follows exactly the
+sequences produced by an xterm rather than the exact VT102/VT220 sequences.
+.I Sympathy
+also recognises the ESC % G and the ESC % @ sequnces to switch between ISO-2202
+and UTF-8 but ignores them (see CHARACTER ENCODING below)
.SH SERIAL PORT THEORY
-.SH FILES
+A serial connexion was originally invisaged to connect a DTE (Data Terminal Eqipment)
+to a DCE (Data Circuit-terminating Equipment). The DCE (some sort of modem) would assert
+the DTE's (the computer or terminal) DSR line to indicate it was ready. The DTE would
+assert DTR to indicate to the DCE that it should attempt a connexion to the remote DCE.
+Once a connexion was established the DCE would assert the DTE's CD pin. Data could then
+flow between the DTR and the remote DTE via the two DCEs. Flow control was provided
+via the RTS CTS lines. The DTE asserts RTS when it is capable of receiving new data,
+and pasues its transmission of data when the CTS line is de-asserted. The local DCE
+asserts CTS when the remote DCE detects RTS, and vice versa.
+.PP
+In modern usage the signals are slightly different, for a typical connexion using modems
+DSR indicates that the modem is ready, a drop DTR is used to indicate to the
+modem that it should break the connexion to the remote modem. CD indicates that
+the local modem is connected to the remote modem, and CTS and RTS behave as before. Connexion
+is established by in-band signalling before CD is asserted.
+.PP
+For a \fBnull modem\fP cable local DSR and DTR are wired to remote CD, local
+CTS to remote RTS, and local RTS to remote CTS. Thus asserting local DTR
+asserts local DSR and remote CD, and asserting local RTS asserts remote CTS.
+.PP
+When RTS/CTS flow control is in operation the operating system or the hardware
+de-asserts RTS when its buffer becomes full causing (via the DCEs or the null
+modem cable) a de-assertion of remote CTS which causes the remote to cease transmission.
.SH EXAMPLES
+.PP
+using sympathy to mimmick screen(1):
+.IP
+[foo@barhost ~]$ sympathy
+.IP
+.I Sympathy
+forks. The child becomes a daemon server and launches a new shell in a
+pseudo-tty, the original process becomes a client and connects to the server
+and shows the output. The user then uses the new shell and after some time
+either hangs up on the client or issues CTRL\-B quit, and the client detaches from
+the server.
+.IP
+Later the user wishes to retreive her session and to determine which sympathy
+sessions are active issues:
+.IP
+[foo@barhost ~]$ sympathy \-ls
+.br
+ barhost.2456 (Active)
+.br
+[root@square ~]$
+.IP
+The user then issues:
+.IP
+[foo@barhost ~]$ sympathy \-r 2456
+.IP
+and is reconnected to her session.
+.PP
+using sympathy to mimick minicom(1):
+.IP
+.IP
+[foo@barhost ~]$ sympathy -t -d /dev/modem -b 9600 -K
+.IP
+.I Sympathy
+opens the device /dev/modem and locks it, sets the baud rate to 9600 baud and disables
+flow control. A VT102 terminal emulator then displays the data from the modem. The user
+quits the emulator by issuing CTRL\-B quit, which unlocks the modem and exits sympathy.
+.PP
+using sympathy to mimick consolidate(1):
+.IP
+.IP
+[foo@barhost ~]$ sympathy -s -d /dev/ttyS13 -b 19200 -K -k /root/sympathy/13 -L /root/sympathy/13.log
+.IP
+.I Sympathy
+becomes a daemon and detaches from the current tty. It then opens the device
+/dev/ttyS13 and locks it, sets the baud rate to 19200 baud and disables flow
+control.
+.I Sympathy
+then listens for clients connecting on the socket -fI/root/sympathy/13-fP, whilst logging
+completed lines and changes in status to the file /root/sympathy/13.log.
+.IP
+A user wishing to see the current status of the /dev/ttyS13 issues:
+.IP
+[foo@barhost ~]$ sympathy -c -k /root/sympathy/13
+.IP
+and the last 200 lines of history are injected into the history of her outer
+terminal emulator and she is connected to /dev/ttyS13.
.SH ERRORS
+
.SH SEE ALSO
screen(1) minicom(1) consolidate(1)
.SH STANDARDS
.SH BUGS
.PD
.IP \(bu 3
+the command line editor should support better line editing and report failed commands
+.IP \(bu 3
when the \-\fBc\fP \-\fBs\fP major mode is used without the \-\fBk\fP option the pid
used in the socket is that of the client process and therefore not unique.
.IP \(bu 3
the HTML generated with the \-\fBH\fP option is ugly.
-.SH SECURITY CONSIDERATIONS
+.IP \(bu 3
+no useful error message is generated if opening the terminal device fails in the
+\-\fBc\fP \-\fBs\fP major mode.
.SH AUTHOR
+James McKenzie, james@fishsoup.dhs.org
~ianmdlvl / sympathy.git / commitdiff