.\" $HeadURL$ $LastChangedRevision$
#spp comment vim: set filetype=nroff: #
#spp include SPPSYM_MODROOT/bldcfg/paths.spp
.\"
.TH PTYPLUMBER 1 "22 July 2006"
.\" If this man page will be released with aderel(1) then uncomment
.\" the following line and comment out the one above.
.\" .TH PTYPLUMBER 1 "SPPSYM_RELEASE_DATE_MAN"
.SH NAME
ptyplumber \- connect pseudoterminals' I/O
.br
.ne 5
.SH SYNOPSIS
.B ptyplumber
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR 
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
]
.br
.ne 5
.SH DESCRIPTION
This manual page documents version SPPSYM_RELEASE_ID of 
.B ptyplumber\fR.
.PP 
.B Ptyplumber
does the following:
.IP
launches user-specified processes (defaulting to
.B bash\fR(1))
in dedicated pseudoterminals,
.IP 
provides commands for connecting the I/O of such programs to/from each other or to/from 
.B ptyplumber\fR's
own standard input and output,
.IP
predefines some access keys for accessing the I/O of its command line interpreter (CLI), its standard input and
output (referred to the
.B console\fR), 
its internal buffering of currently unconnected I/O and its bitbucket.
.PP
In order to harmonise use of pseudo-terminals' file descriptors and the predefined access keys, 
.B ptyplumber
introduces the idea of 
.I pseudo file descriptors
(PFDs), which are numerical keys assigned by
.B ptyplumber\fR.
Since these are not assigned by the user, user-defined aliases for PFDs are also supported.
does stuff that has not yet been documented.
.PP
The commands that 
.B ptyplumber\fR's
CLI understands are:
.TP 25
.B open \fR[ \fIcmd \fR]
launches 
.I cmd
in a new PFD; its I/O is left disconnected but buffered.
.TP
.B close \fIpfd \fR[ ... ]
closes the specified PFDs, terminating the processes running on their slave sides.
.TP
.B connect \fR[ \fIpfdout \fR] \fIpfdin\fR
connects the output of the process attached to
.I pfdout
(defaults to the console PFD).
If pfdout
is the console PFD (and the CLI thereby is suspended) then the connection status can then be modified
by using escape sequences:
.RS 25
.TP 10
.B !d
disconnect (or rather: connect console to CLI)
.TP
.B !!
send a literal !
.TP
.B !?
show help on escape sequences
.RE
.TP
.B disconnect \fIpfdout\fR
disconnect the output of 
.I pfdout\fR.
Output sent from this PFD while it remains unconnected will be buffered if autobuffering is enabled (see the
.B set
comamnd below).
.TP
.B echo \fR[ \fIpfd \fR] \fItext
sends 
.I text
to the specified PFD (default 
.B ptyplumber\fR's 
standard output.
.TP 
.B set \fRpfd \fR[ \fIproperty \fR[ \fI value \fR ] ]
displays or sets the binary property of the specified PFD. 
.I Property
can be one of 
.B autobuf
(output will be automatically buffered after PFD is disconnected,
output will be automatically disacard after PFD is disconnected).
.TP
.B list
List status of all PFDs.
.br
.ne 5
.SH CONFIGURATION
None.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B ptyplumber
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B ptyplumber
uses.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B ptyplumber
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
The following will connect together two PPP daemons running on remote machines 'apple' and 'banana':
.IP
.nf
.fam C
.B open --alias=apple "telnet apple"
.B open --alias=banana "ssh banana"
.B connect apple 
.B alexis
.B mypassword
.B su -
.B rootpassword
.B pppd 192.168.10.1: noauth
.B !d
.B connect banana
.B myotherpassword
.B su -
.B rootpassword
.B pppd 192.168.20.1: noauth
.B !d
.B connect banana apple
.B connect apple banana
.fam T
.fi
.br
.ne 5
.SH CAVEATS
PFD aliases have not yet been implemented.
.br
.ne 5
.SH SEE ALSO
bash(1), screen(1), pty(7)
.br
.ne 5
.SH AUTHOR
SPPSYM_AUTHOR_NAME <SPPSYM_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2006-SPPSYM_RELEASE_YEAR SPPSYM_AUTHOR_NAME
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.