Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / IO::Pty.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pty 3"
.TH Pty 3 "2002-04-02" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
IO::Pty \- Pseudo TTY object class
.SH "VERSION"
.IX Header "VERSION"
1.02
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use IO::Pty;
.Ve
.PP
.Vb 1
\&    $pty = new IO::Pty;
.Ve
.PP
.Vb 1
\&    $slave  = $pty->slave;
.Ve
.PP
.Vb 5
\&    foreach $val (1..10) {
\&        print $pty "$val\en";
\&        $_ = <$slave>;
\&        print "$_";
\&    }
.Ve
.PP
.Vb 1
\&    close($slave);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`IO::Pty\*(C'\fR provides an interface to allow the creation of a pseudo tty.
.PP
\&\f(CW\*(C`IO::Pty\*(C'\fR inherits from \f(CW\*(C`IO::Handle\*(C'\fR and so provide all the methods
defined by the \f(CW\*(C`IO::Handle\*(C'\fR package.
.PP
Please note that pty creation is very system\-dependend.  If you have
problems, see IO::Tty for help.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new" 3
.IX Item "new"
The \f(CW\*(C`new\*(C'\fR constructor takes no arguments and returns a new file
object which is the master side of the pseudo tty.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fIttyname()\fR" 4
.IX Item "ttyname()"
Returns the name of the slave pseudo tty. On \s-1UNIX\s0 machines this will
be the pathname of the device.  Use this name for informational
purpose only, to get a slave filehandle, use \fIslave()\fR.
.IP "\fIslave()\fR" 4
.IX Item "slave()"
The \f(CW\*(C`slave\*(C'\fR method will return the slave filehandle of the given
master pty, opening it anew if necessary.  If IO::Stty is installed,
you can then call \f(CW\*(C`$slave\->stty()\*(C'\fR to modify the terminal settings.
.IP "\fIclose_slave()\fR" 4
.IX Item "close_slave()"
The slave filehandle will be closed and destroyed.  This is necessary
in the parent after forking to get rid of the open filehandle,
otherwise the parent will not notice if the child exits.  Subsequent
calls of \f(CW\*(C`slave()\*(C'\fR will return a newly opened slave filehandle.
.IP "\fImake_slave_controlling_terminal()\fR" 4
.IX Item "make_slave_controlling_terminal()"
This will set the slave filehandle as the controlling terminal of the
current process, which will become a session leader, so this should
only be called by a child process after a \fIfork()\fR, e.g. in the callback
to \f(CW\*(C`sync_exec()\*(C'\fR (see Proc::SyncExec).  See the \f(CW\*(C`try\*(C'\fR script
(also \f(CW\*(C`test.pl\*(C'\fR) for an example how to correctly spawn a subprocess.
.IP "\fIset_raw()\fR" 4
.IX Item "set_raw()"
Will set the pty to raw.  Note that this is a one-way operation, you
need IO::Stty to set the terminal settings to anything else.
.Sp
On some systems, the master pty is not a tty.  This method checks for
that and returns success anyway on such systems.  Note that this
method must be called on the slave, and probably should be called on
the master, just to be sure, i.e.
.Sp
.Vb 2
\&  $pty->slave->set_raw();
\&  $pty->set_raw();
.Ve
.IP "clone_winsize_from(\e*FH)" 4
.IX Item "clone_winsize_from(*FH)"
Gets the terminal size from filehandle \s-1FH\s0 (which must be a terminal)
and transfers it to the pty.  Returns true on success and undef on
failure.  Note that this must be called upon the \fIslave\fR, i.e.
.Sp
.Vb 1
\& $pty->slave->clone_winsize_from(\e*STDIN);
.Ve
.Sp
On some systems, the master pty also isatty.  I actually have no
idea if setting terminal sizes there is passed through to the slave,
so if this method is called for a master that is not a tty, it
silently returns \s-1OK\s0.
.Sp
See the \f(CW\*(C`try\*(C'\fR script for example code how to propagate \s-1SIGWINCH\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::Tty, IO::Tty::Constant, IO::Handle, Expect, Proc::SyncExec
.SH "MAILING LISTS"
.IX Header "MAILING LISTS"
As this module is mainly used by Expect, support for it is available
via the two Expect mailing lists, expectperl-announce and
expectperl\-discuss, at
.PP
.Vb 1
\&  http://lists.sourceforge.net/lists/listinfo/expectperl-announce
.Ve
.PP
and
.PP
.Vb 1
\&  http://lists.sourceforge.net/lists/listinfo/expectperl-discuss
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Originally by Graham Barr <\fIgbarr@pobox.com\fR>, based on the
Ptty module by Nick Ing-Simmons <\fInik@tiuk.ti.com\fR>.
.PP
Now maintained and heavily rewritten by Roland Giersig
<\fIRGiersig@cpan.org\fR>.
.PP
Contains copyrighted stuff from openssh v3.0p1, authored by 
Tatu Ylonen <ylo@cs.hut.fi>, Markus Friedl and Todd C. Miller
<Todd.Miller@courtesan.com>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Now all code is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.PP
Nevertheless the above \s-1AUTHORS\s0 retain their copyrights to the various
parts and want to receive credit if their source code is used.
See the source for details.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
\&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 ``\s-1AS\s0 \s-1IS\s0'' \s-1AND\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0
\&\s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0 \s-1ARE\s0 \s-1DISCLAIMED\s0.
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0 \s-1THE\s0 \s-1AUTHORS\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1DIRECT\s0, \s-1INDIRECT\s0,
\&\s-1INCIDENTAL\s0, \s-1SPECIAL\s0, \s-1EXEMPLARY\s0, \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 (\s-1INCLUDING\s0,
\&\s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1PROCUREMENT\s0 \s-1OF\s0 \s-1SUBSTITUTE\s0 \s-1GOODS\s0 \s-1OR\s0 \s-1SERVICES\s0; \s-1LOSS\s0
\&\s-1OF\s0 \s-1USE\s0, \s-1DATA\s0, \s-1OR\s0 \s-1PROFITS\s0; \s-1OR\s0 \s-1BUSINESS\s0 \s-1INTERRUPTION\s0) \s-1HOWEVER\s0 \s-1CAUSED\s0 \s-1AND\s0
\&\s-1ON\s0 \s-1ANY\s0 \s-1THEORY\s0 \s-1OF\s0 \s-1LIABILITY\s0, \s-1WHETHER\s0 \s-1IN\s0 \s-1CONTRACT\s0, \s-1STRICT\s0 \s-1LIABILITY\s0, \s-1OR\s0
\&\s-1TORT\s0 (\s-1INCLUDING\s0 \s-1NEGLIGENCE\s0 \s-1OR\s0 \s-1OTHERWISE\s0) \s-1ARISING\s0 \s-1IN\s0 \s-1ANY\s0 \s-1WAY\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0
\&\s-1USE\s0 \s-1OF\s0 \s-1THIS\s0 \s-1SOFTWARE\s0, \s-1EVEN\s0 \s-1IF\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0
\&\s-1DAMAGE\s0.
.PP
In other words: Use at your own risk.  Provided as is.  Your mileage
may vary.  Read the source, Luke!
.PP
And finally, just to be sure:
.PP
Any Use of This Product, in Any Manner Whatsoever, Will Increase the
Amount of Disorder in the Universe. Although No Liability Is Implied
Herein, the Consumer Is Warned That This Process Will Ultimately Lead
to the Heat Death of the Universe.