.SH NAME
sympathy \- client/server terminal emulator with logging
.SH SYNOPSIS
+.B sympathy \-\fBt\fP
+[
+.B \fIterminal_options\fP
+] [
+.B \fIdisplay_options\fP
+]
+.br
+.B sympathy \-\fBs\fP
+[
+.B \fIterminal_options\fP
+] [
+.B \fIserver_options\fP
+]
+.br
+.B sympathy
+[
+.B \-\fBc\fP \-\fBs\fP
+] [
+.B \fIterminal_options\fP
+] [
+.B \fIserver_options\fP
+] [
+.B \fIclient_options\fP
+]
+.br
+.B sympathy \-\fBc\fP
+[
+.B \fIclient_options\fP
+]
+.br
+.B sympathy \-\fBr\fP
+id
+[
+.B \fIclient_options\fP
+]
+.br
+.B sympathy \-\fBv\fP
+.br
.\" "sympathy -t [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u]\n"
.\" "sympathy -s [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n"
.\" " [-n hlines] [-w WxH] [-F]\n"
.\" "sympathy -h\n"
.SH DESCRIPTION
+.I Sympathy
+is a VT52/VT100/ANSI terminal emulator with some special features. In normal use
+.I sympathy
+would sit between a terminal device (a serial port or a ptty) and
+the user's usual terminal emaulator (eg xterm(1)).
+.I Sympathy
+renders data from the terminal device into an internal frame buffer
+and then expresses changes in this frame buffer to the outer terminal
+emulator using a small subset of ANSI escape codes.
+.I Sympathy
+always generates valid escape codes to the outer terminal, and will
+reset the state of its internal terminal emulator when it detects
+framing errors on the terminal device.
+.PP
+.I Sympathy\fP,
+unlike screen(1), takes care to preserve the scrollback features
+of the outer terminal emulator: lines that scroll of the top of the internal
+frame buffer are scrolled off the top of the outer terminal emaultor. When
+sympathy is used in client/server mode, some history is added to the outer
+terminal emulator when the client connects.
+.PP
+.I Sympathy
+also supports automatic baud rate detection, and advanced logging features.
+.I Sympathy
+logs whenever any of the modem control lines change state, receive errors,
+and the contents
+of any line on the frame buffer as the cursor moves off it.
.SH OPTIONS
+.B \fImajor mode options\fP:
+.TP 5
+.B \-t
+act as terminal emulator only:
+.I sympathy
+opens the terminal device and outputs into the outer terminal emulator, when sympathy exits the
+device is closed and no process remains. In this mode sympathy behaves like a traditional
+terminal emulator such as cu(1) or minicom(1).
+.TP 5
+.B \-s
+act as server only:
+.I sympathy
+opens the terminal device and renders into an internal frame buffer, listens for clients
+on the socket and logs activity. By default the server will fork into a daemon processes
+but can be forced to remain in the forground with the \-\fBF\fP option.
+.TP 5
+.B \-c\fP or \fB\-r\fP \fIid\fP
+act as client only:
+.I sympathy
+connects to a sympathy server process and injects the history into the outer terminal
+emulator,
+and connects the user with the terminal device. One server process can support multiple
+client processes. This mode can also be used to obtain a dump of the current screen
+in HTML format (see the \-\fBH\fP option). The \-\fPr\fP option connects to a server
+on the socket ~/.sympathy/\fIid\fP or if \fIid\fP is an integer
+~/.sympathy/\fIhostname\fP.\fIid\fP mimicking the behaviour of screen(1). With the
+\-\fBc\fP option the socket must be specified with the \-\fBk\fP option.
+.TP 5
+.B \fP[\fB \-c \-s \fP]
+act as both client and server:
+.I sympathy
+forks. The child process becomes a server, and the orginal process becomes a client
+which then connects to the server. This is the default major mode if no other is specified.
+Since the default terminal device is a ptty, running
+.I sympathy
+with no arguments will start a new shell in a daemonized process and connect to it
+as a client from the original process, mimicking the behaviour of screen(1)
+.TP 5
+.B \-l\fP or \fB\-ls
+show active sockets:
+.I sympathy
+will show active sockets, ones to which a call to connect(2) succeeds,
+in ~/.sympathy. If the socket name begins with the hostname of the machine, and
+the call to connect(2) fails, then socket will be unlinked.
+.TP 5
+.B \-v
+show current version:
+.I sympathy
+will print the the version number of the code it was compiled with.
+.TP 5
+.B \-h
+show help:
+.I sympathy
+will show brief usage instructions
+.PP
+.B \fIterminal_options\fP:
+.TP 5
+.B \-d \fIserialdev\fP
+connect to terminal device \fIserialdev\fP, eg /dev/ttyS0.
+By default
+.I sympathy
+doesn't
+lock the terminal device, but checks periodically for lock files of other processes. If
+sympathy detects another lock file it displays \fBLocked\fP in the status line
+and refuses I/O on the device until the lock file is removed or becomes invalid.
+To lock the device use the \-\fBK\fP option.
+.I Sympathy
+will in addition check that the name of the device does not occur in /proc/cmdline
+as an argument to the \fIconsole\fP kernel parameter.
+The \-\fBd\fP option is incompatible with the \-\fBp\fP option.
+.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
+terminal device if none is specified.
+.TP 5
+.B \-K
+lock the terminal device specificed in the \-\fBd\fP option.
+.I Sympathy
+generates lock files in a staggering variety of formats and places. For locks
+based on the name of the device sympathy generates lock files for all devices
+with the same major and minor in /dev, /dev/usb and /dev/tts, it uses both normal
+and lower case and replaces occurances of '/' in the device name with both '.' and '_'.
+.I Sympathy
+also generates locks based on the device major and minor numbers, and for all lock file
+names generates them in any of the follwoing directories that are writable:
+/var/lock/uucp, /var/spool/lock, /var/spool/uucp, /etc/locks, /usr/spool/uucp,
+/var/spool/locks, /usr/spool/lock, /usr/spool/locks, /usr/spool/uucp/LCK, /var/lock.
+Lock files are assumed to be in HDB format.
+.TP 5
+.B \-b \fIbaudrate\fP
+set the baud rate of the terminal device specificed in the \-\fBd\fP to baudrate, if omitted
+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
+\fIc_cflag\fPs of \fICS8|CREAD|CLOCAL\fP.
+.TP 5
+.B \-L \fIlogfile\fP
+log activity to the file \fIlogfile\fP. If \fIlogfile\fP is '-' then log to \fIstdout\fP. Note
+that logging to \fIstdout\fP only makes sense with the \-\fBF\fP \fIserver_option\fP.
+.TP 5
+.B \-w \fIwidth\fP[x\fIheight\fP]
+set the initalize size of the terminal emulator's frame buffer to be \fIwidth\fP columns
+by \fIheight\fP rows. If \fIheight\fP is ommited it defaults to 24, the default width
+is 80. These values may
+be overridden later by terminal escape sequences. If \-\fBp\fP is also specificed
+the ptty will have its window size set to match.
+.PP
+.B \fIdisplay_options\fP:
+.TP 5
+.B \-u
+attempt to render unicode characters in the internal frame buffer to the outer terminal
+emulator by using ISO-2202 sequences.
+.I Sympathy
+currently only checks to see if an appropriate character appears in the VT102
+US character set, or in the VT102 'special characters and line drawing' character set.
+If the character appears in neither of these then it will be rendered on the outer
+terminal emulator as a '?'.
+.TP 5
+.B \-H
+render the current state of the internal frame buffer to stdout as HTML, then quit.
+.PP
+.B \fIclient_options\fP:
+.TP 5
+.B -k \fIsocket\fP
+set the name in the filesystem of the socket to which
+.I sympathy
+should connect. This option is \fBmanditory\fP unless the \-\fBs\fP or \-\fBr\fP options
+have also been given. If \-\fBs\fP is given then it will default to the socket which
+the forked server process opens. See the discusion of the \-\fPr\fP option above, for
+information on how
+.I sympathy
+chooses a socket name if \-\fBr\fP is specified.
+.PP
+.B \fIserver_options\fP:
+.TP 5
+.B -k \fIsocket\fP
+set the name in the filesystem of the socket on which
+.I sympathy
+should listen for clients. If this option is omitted
+.I sympathy
+will create a
+socket in ~/.sympathy, creating that directory if neccessary, and named
+\fIhostname\fP.\fIpid\fP where \fIpid\fP is the process id of the
+.I sympathy
+process that created the socket.
+.TP 5
+.B -F
+tells the
+.I sympathy
+server process not to become a daemon but to remain the the foreground. This option is
+incompatible with the \-\fBc\fP \-\fBs\fP major mode.
+.TP 5
+.B -n \fInlines\fP
+sets the number of lines of history that the server process stores to \fInlines\fP. When
+a client connects \fInlines\fP of history are injected into the outer terminal emulator
+so that they can be seen when scrolling back. By default the server stores 200 lines of
+history.
+.SH OPERATION
+When
+.I sympathy
+is relaying data to the outer terminal emulator a reverse video status line
+will be visible at the bottom of the screen. The status line shows pertinent
+information. The first item on the line reminds you what the current escape character
+is, the second indicates the terminal device to which
+.I sympathy
+is connected, and the third shows the current baudrate. Other messages are:
+.TP 5
+.B Flow
+indicates that that RTS/CTS flow control is in operation on the terminal device.
+.TP 5
+.B RTS
+indicates that the terminal device is asserting the RTS line which indicates that
+the local system is ready to accept data from the remote system. If RTS/CTS
+flow control is in operation then the operating system or hardware may
+de-assert RTS even if RTS is shown. See the section on SERIAL PORT THEORY for
+more information.
+.TP 5
+.B CTS
+indicates that the terminal device has detected that the local system's CTS
+line is being asserted, indicating that the remote system is ready to receive
+data from the local system. See the section on SERIAL PORT THEORY for
+more information.
+.TP 5
+.B DTR
+indicates that the terminal device is asserting the DTR line indicating that the local
+system would like the local DCE to establish a connection to the remote
+DCE. See the section on SERIAL PORT THEORY for more information.
+.TP 5
+.B DSR
+indicates that the terminal device has detected that the local system's DSR line is
+being asserted, indicating that the local DCE is ready. See the section on
+SERIAL PORT THEORY for more information.
+.TP 5
+.B CD
+indicates that the terminal device has detected that the local system's CD line is
+being asserted, indicating that the local DCE has a connection to the remote DCE.
+See the section on SERIAL PORT THEORY for more information.
+.TP 5
+.B RI
+indicates that the terminal device has detected that the local system's RI line is
+being asserted, indicating that the DCE has detected a ringing signal or incoming
+connexion.
+.TP 5
+.B n clients
+shows the number of connected client processes. In the \-\fBt\fP major mode, this will
+always be zero.
+.TP 5
+.B Locked
+the terminal device was opened without the \-\fbK\fP flag and another process is
+currently using it. I/O to the device is currently suspended until the process dies
+or removes its lock file.
+.TP 5
+.B n errs
+indicates the number of frames recived by the terminal device with errors. The count
+resets if no errors are detected by the device for 10 seconds.
+
+
+.PP
+ you can send commands by sending
+ascii(7) STX from the outer terminal emulator (usally by pressing CTRL-B).
+
+the s
+.SH LOG FILES
.SH EXIT STATUS
.SH ENVIRONMENT
+.SH SERIAL PORT THEORY
.SH FILES
.SH EXAMPLES
.SH ERRORS
screen(1) minicom(1) consolidate(1)
.SH STANDARDS
.SH BUGS
+.PD
+.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
.SH AUTHOR
-.\" vi: set syn=groff
~ianmdlvl / sympathy.git / commitdiff