Pty(3)

📦
version 1.20 · 15 versions
, in centos-stream 10

💖 Pty(3) — IO::Pty, but make it make sense 💖

okay so bestie, this is a page from the User Contributed Perl Documentation (section 3 of your man pages, iykyk) and it's all about IO::Pty. grab a snack, we're learning about pseudo terminals 🫶

✨ NAME ✨

IO::Pty — the Pseudo TTY object class 💅

🎀 VERSION 🎀

1.20

🌸 SYNOPSIS 🌸

ok so here's the vibe in code form, literally just copy this energy:

use IO::Pty;

$pty = new IO::Pty;

$slave  = $pty->slave;

foreach $val (1..10) {
    print $pty "$val\n";
    $_ = <$slave>;
    print "$_";
}

close($slave);

🦋 DESCRIPTION 🦋

"IO::Pty" hands you an interface so you can create a pseudo tty. that's the whole gig ✨

it inherits from "IO::Handle", so it provides all the methods that the "IO::Handle" package defines. free real estate, we love to see it 👑

⚠️ real talk: pty creation is very system-dependent. like, extremely. if you're having problems (and you might 😭), go see IO::Tty for help. it's giving "read the other page first".

💜 CONSTRUCTOR 💜

  • new — the "new" constructor takes no arguments and returns a new file object which is the master side of the pseudo tty. main character energy, no params needed 💅

⭐ METHODS ⭐

  • ttyname() — returns the name of the slave pseudo tty. on UNIX machines this will be the pathname of the device. use this name for informational purpose only — if you actually want a slave filehandle, use slave(). don't come for me, that's just the rules 🫶
  • slave() — the "slave" method returns the slave filehandle of the given master pty, opening it anew if necessary. if IO::Stty is installed, you can then call "$slave->stty()" to modify the terminal settings. slay 💖
  • close_slave() — the slave filehandle gets 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 😭 (imagine not knowing your child left. tragic.) subsequent calls of slave() will return a newly opened slave filehandle.
  • make_slave_controlling_terminal() — this sets 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 fork(), e.g. in the callback to sync_exec() (see Proc::SyncExec). check the "try" script (also "test.pl") for an example of how to correctly spawn a subprocess. it's giving "only the child gets to do this, periodt" 👑
  • set_raw() — sets the pty to raw. note that this is a one-way operation — you need IO::Stty to set the terminal settings to anything else. no take-backsies 🙈

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 too, just to be sure, i.e.

$pty->slave->set_raw();
$pty->set_raw();

(do both. trust the process. 💅)

  • clone_winsize_from(\*FH) — gets the terminal size from filehandle FH (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 slave, i.e.
$pty->slave->clone_winsize_from(\*STDIN);

on some systems, the master pty also isatty. honestly, the docs straight up say they 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 OK 😭 (yes, it just says ok and moves on, iconic behaviour tbh).

see the "try" script for example code on how to propagate SIGWINCH.

  • get_winsize() — returns the terminal size, in a 4-element list.
($row, $col, $xpixel, $ypixel) = $tty->get_winsize()
  • set_winsize($row, $col, $xpixel, $ypixel) — sets the terminal size. if not specified, $xpixel and $ypixel are set to 0. as with "clone_winsize_from", this must be called upon the slave.

🌈 SEE ALSO 🌈

IO::Tty, IO::Tty::Constant, IO::Handle, Expect, Proc::SyncExec

(go read all of them, bestie, they're literally the friend group 🫶)

💌 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

http://lists.sourceforge.net/lists/listinfo/expectperl-announce

and

http://lists.sourceforge.net/lists/listinfo/expectperl-discuss

👑 AUTHORS 👑

originally by Graham Barr <gbarr@pobox.com>, based on the Ptty module by Nick Ing-Simmons <nik@tiuk.ti.com>.

now maintained and heavily rewritten by Roland Giersig <RGiersig@cpan.org>.

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

(credit where credit is due, always 🫶)

now all code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

nevertheless the above AUTHORS retain their copyrights to the various parts and want to receive credit if their source code is used. see the source for details.

💀 DISCLAIMER 💀

ok so this part is the legal bit and it's a LOT, but you gotta read it, no skipping 😤

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

in other words: use at your own risk. provided as is. your mileage may vary. read the source, Luke! 🔥

and finally, just to be sure:

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.

(yes bestie, this module is technically speeding up the heat death of the universe. we stan an honest disclaimer 😭💜)

🌸 that's the whole page! this one shipped as perl v5.40.0, dated 2024-10-29, and it's Pty(3) in the manual — go forth and pseudo-terminal responsibly, love u 🎀✨

📦 where this page comes from