From 191454e17fb1de32194ed420544836d759a8802e Mon Sep 17 00:00:00 2001 From: james Date: Wed, 27 Feb 2008 18:29:49 +0000 Subject: [PATCH] *** empty log message *** --- Makefile.am | 12 ++- apps/usage.c | 12 ++- sympathy.1 | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 313 insertions(+), 9 deletions(-) diff --git a/Makefile.am b/Makefile.am index b82e068..a6250cd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -8,6 +8,9 @@ # $Id$ # # $Log$ +# Revision 1.7 2008/02/27 18:29:49 james +# *** empty log message *** +# # Revision 1.6 2008/02/27 16:01:24 james # *** empty log message *** # @@ -55,20 +58,21 @@ VCHK=${shell cat ${VFS} | @MD5SUM@ | @AWK@ '{print $$1 }' } VNUM=${shell @GREP@ ${VCHK} ${VFD}/version-md5sums | @AWK@ '{ print $$2 }' } VSTP=${shell @GREP@ ${VCHK} ${VFD}/version-stamps | @AWK@ 'BEGIN { FS="\t" }; { print $$2 }' } VDEF=${shell echo `cat ${VFD}/version-major`.`cat ${VFD}/version-minor`.`cat ${VFD}/version-micro` } +VSDF=${shell tail -1 ${VFD}/version-stamps | @AWK@ 'BEGIN { FS="\t" }; { print $$2 }' } -EXTRA_DIST=version-files version-major version-minor version-micro version-md5sums version-stamps +EXTRA_DIST=version-files version-major version-minor version-micro version-md5sums version-stamps sympathy.1 version.sed: $(VFD)/version-files $(VFD)/version-major \ $(VFD)/version-minor $(VFD)/version-micro \ $(VFD)/version-md5sums $(VFD)/version-stamps ${VFS} Makefile if [ .${VNUM} = . ]; then \ echo "s/%VERSION%/${VDEF}-E/g" > version.sed; \ - echo "s/%VERSIONSTAMP%/After ${VSTP}/g" >> version.sed; \ - echo "s/%LONGVERSION%/libsympathy version ${VNUM} + Edits/g" >> version.sed; \ + echo "s/%VERSIONSTAMP%/After ${VSDF}/g" >> version.sed; \ + echo "s/%LONGVERSION%/Version ${VDEF} + Edits/g" >> version.sed; \ else \ echo "s/%VERSION%/${VNUM}/g" > version.sed; \ echo "s/%VERSIONSTAMP%/${VSTP}/g" >> version.sed; \ - echo "s/%LONGVERSION%/libsympathy version ${VNUM}/g" >> version.sed; \ + echo "s/%LONGVERSION%/Version ${VNUM}/g" >> version.sed; \ fi protos: diff --git a/apps/usage.c b/apps/usage.c index 5a00619..d76f9d9 100644 --- a/apps/usage.c +++ b/apps/usage.c @@ -10,6 +10,9 @@ static char rcsid[] = "$Id$"; /* * $Log$ + * Revision 1.16 2008/02/27 18:29:49 james + * *** empty log message *** + * * Revision 1.15 2008/02/27 16:01:24 james * *** empty log message *** * @@ -65,11 +68,12 @@ usage (void) { fprintf (stderr, "Usage:\n" - "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" + "sympathy -t [-K] [-d serialdev|-p] [-b baud] [-f] [-L log]\n" + " [-w WxH] [-u]\n" + "sympathy -s [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-k skt]\n" " [-n hlines] [-w WxH] [-F]\n" - "sympathy [-s -c] [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-u] [-k skt]\n" - " [-n hlines] [-w WxH]\n" + "sympathy [-s -c] [-K] [-d serialdev|-p] [-b baud] [-f] [-L log] [-k skt]\n" + " [-n hlines] [-w WxH] [-u]\n" "sympathy -c [-H] [-u] -k skt\n" "sympathy -r id [-H] [-u]\n" "sympathy {-l|-ls}\n" diff --git a/sympathy.1 b/sympathy.1 index 06afdbc..8da2be1 100644 --- a/sympathy.1 +++ b/sympathy.1 @@ -2,6 +2,44 @@ .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" @@ -14,9 +52,262 @@ sympathy \- client/server terminal emulator with logging .\" "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 @@ -24,6 +315,11 @@ sympathy \- client/server terminal emulator with logging 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 -- 2.30.2