-*-text-*-
$Header: /CVSROOT/ptybuffer/README,v 1.8 2007/08/29 22:23:48 tino Exp $

Tired reading docs?

make
./ptybuffer
head test/test.sh


Changes
=======

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.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
