-*-text-*- $Header: /CVSROOT/ptybuffer/README,v 1.10 2007-09-27 15:39:42 tino Exp $ Tired reading docs? make ./ptybuffer head test/test.sh Changes ======= 2007-09-27 0.6.4 Now compiles under CygWin again 2007-09-21 0.6.3 Scripts under CLL, fixed minor resource leakage 2007-09-18 0.6.2 important bugfix 2007-08-30 0.6.1 Usage fixed 2007-08-29 0.6.0 bugfix, options -i -k 2007-08-29 0.5.12 bugfix for more than 2^31 read()s from pty 2007-08-25 0.5.11 options -p -q. early 0.6.0 for ptybufferconnect 2007-06-01 0.5.10 bugfix for 0.5.9 2007-04-29 0.5.9 changes (which did not work) 2007-04-19 0.5.8 (don't know) 2007-04-07 0.5.7 better cron support in script/autostart.sh 2007-03-31 0.5.6 bugfix script/autostart.sh 2007-03-26 0.5.5 Cygwin fixes 2007-03-26 0.5.4 bugfix for 0.5.3 2007-03-04 0.5.3 log/outfile via realpath(), script/autostart.sh 2006-08-16 0.5.2 bugfix for 0.5.1 2006-08-11 0.5.1 bugfix: did not work without -c any more 2006-06-26 0.5.0 options -t, -c, -f 2006-04-12 0.4.0 worksock from stdin, fresh tinolib, histsize 2004-11-12 0.3.1 buffix options -l and -o 2004-10-23 0.3.0 Options, minor bugfix, restructuring contents 2004-07-05 0.2.4 NWNadm 2.6.2 2004-06-13 0.2.3 fix in socket implementation 2004-06-03 0.2.2 NWNadm updates 2004-05-21 0.2.1 memory corruption fix 2004-05-20 0.2.0 nwn directory 2004-05-20 0.1.0 initial version ptybuffer ========= WARNING! THIS IS RELEASE EARLY CODE! ptybuffer does following: - Daemonizes (if option -d is not present), else runs in foreground - Calls a process (arg2 and above) with a pty such that stdlib usually makes output line buffered. - Gathers the output history of the pty for later view. Currently this is 1000 reads (not neccessarily lines, see option -n). - Waits for connects to the unix socket (command line argument 1) - Outputs the pty history to the connected unix socket and continuously sends all new output to the connected unix socket. - Read (full) lines from the connected unix sockets and send them to the pty (line can be max. 4095 bytes long). - Allows multiple concurrent connects to the unix socket. This way several persons in parallel can control one process. This has several improvements over screen: - Screen blocks all connects if one session freezes. ptybuffer is thought to always let the program run, regardless what mess the socket connections might do. In case of a connect stall it just discards data to the frozen connect and if the connect catches up it tells it the fact. - Concurrent access is no problem. Lines are always send as full lines. - History of output is clearly defined, not just something like a window. - Naturally scrolling logfile support. Eases development in case you have excessive debugging active and want to see the output as soon as it comes from the program, even without shell access. - You can control where the socket is. This improves oversight in case you have running several commands in parallel. - Easy to use from web scripting languages like PHP which can directly connect to a Unix Domain Socket. Really no need to use error prone constructs like expect. Bugs: ===== - ptybuffer does not unlink() the socket if option -f and -c are missing. This is a feature. - The program running under pty control is not considered to stop. If this ever happens, ptybuffer just exits without making sure that all data is sent to connected sockets. - New version have not been tested much before release. - If you send data to ptybuffer and close the socket very fast, the EOF on the write side closes the socket before everything can be read from the read side by the select-loop. Luckily, usually not much is sent to the controlled process this way (one line or so), so a short sleep should be enough for ptybuffer to gather the data. To fix this BUG I must implement the socket flags first and restructure the the EOF processing a bit - no time for it now, it currently works good enough for me. Example: ======== See introductory comment in test/test.sh For a PHP usage example see the nwn/ subdirectory (footnote [0]) You need a program capable to send data to unix sockets to test ptybuffer. The only two programs I know to be capable of this easily is netpipes and my utility accept (version 2), see http://www.scylla-charybdis.com/tools.html in the (old) tools section. Install: ======== Just type make Was tested to compile under RedHat 9 and SuSE 9. There is no install or similar. Just run it from the source directory or copy it where you want to have it. DISCLAIMER: =========== USE AT YOUR OWN RISK! I CANNOT ACCEPT ANY LIABLILITY FOR ANYTHING! THIS *IS* RELEASE EARLY CODE! IT IS CONSIDERED TO BE INSTABLE! DON'T TRUST SOURCES! READ THEM! READ THEM AGAIN! AND BE SURE THERE ARE NO KNOWN BACKDOORS IN THEM! IT'S OPEN SOURCE, SO YOU CAN CHECK! I tried my best. However I am human. So I make mistakes. Be prepared. All I guarantee is, that I never do anything to harm *you* by purpose. Copyright (C)2004 by Valentin Hilbig ptybuffer may be distributed freely under the conditions of the GPL2 (GNU General Public License version 2) or higher. Footnotes: ========== [0] ptybuffer was programmed to control the servers for a new persistent NWN[1] world which heavily uses NWNX/APS and a database driven BIC file editor (BIC -> SQL -> DB -> XML -> BIC) which is likely to be released publicly in future under the GPL, too. [1] Neverwinter Nights etc. are the trademark of Bioware INC, see http://nwn.bioware.com/ -Tino webmaster@scylla-charybdis.com http://www.scylla-charybdis.com/ $Log: README,v $ Revision 1.10 2007-09-27 15:39:42 tino CygWin fixes Revision 1.9 2007/09/21 11:14:29 tino New dist Revision 1.8 2007/08/29 22:23:48 tino 0.6.1 usage fixed Revision 1.7 2007/08/29 20:30:11 tino Bugfix (int -> long long) and ptybufferconnect -i Revision 1.6 2006/08/11 22:09:07 tino Bugfix (for missing option -c) child status is logged (and returned for option -d) Revision 1.5 2006/07/26 12:20:21 tino options -c, -f and release Revision 1.4 2006/04/11 22:08:12 tino new release Revision 1.3 2004/10/22 01:12:23 tino now reflects the new options Revision 1.2 2004/05/20 09:53:11 tino release texts