<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from IO/Tty.rs. Do not edit. -->

```{index} single: IO::Tty
```

# IO::Tty

```{pperl-module-badges} IO::Tty
```

Pseudo-terminals and the terminal constants: the compiled part under
`IO::Pty` (a pty master and its slave as handles) and `IO::Tty`.


## Synopsis

```perl
use IO::Pty;
my $pty = IO::Pty->new;               # IO::Pty::pty_allocate
my $slave = $pty->slave;              # IO::Tty::_open_tty
print $pty->ttyname, "\n";            # e.g. /dev/pts/3

use IO::Tty qw(TIOCSWINSZ);           # IO::Tty::Constant
my $ws = IO::Tty::pack_winsize(24, 80);
```

## How it works

`IO::Pty::pty_allocate` returns a pty's master and slave descriptors
and the slave's name, or an empty list. It tries `posix_openpt`, then
`getpt`, `openpty` and `/dev/ptmx`, then the BSD-style `/dev/pty??`
names; for each master it grants and unlocks the slave, names it with
`ptsname_r` or `ptsname`, opens it, and moves both descriptors above
2. With `$IO::Tty::DEBUG` true it says on stderr what it tries; with
`use warnings` (category `io`) each method that fails warns.
`IO::Tty::_open_tty` opens a terminal by name, `ttyname` names a
handle's terminal, and `pack_winsize`/`unpack_winsize` convert a
`struct winsize`. Loading defines the constants of `IO::Tty::Constant`,
undef for the ones this system lacks, and `$IO::Tty::CONFIG`.

This is a native implementation of `Tty.xs` of IO-Tty 1.31 as its
Makefile.PL configures it on Linux, with the `xssubs.c` it writes;
`IO/Tty.pm`, `IO/Pty.pm` and the `IO/Tty/Constant.pm` it writes are
used unchanged.

## Differences from upstream

One, where perl 5.44 with Tty.xs crashes or reports memory it never
wrote (t/81-xs-native/IO-Tty/150-or-better.t):

- `unpack_winsize` of a value with no string - undef, a number, a
  reference - dies "Bad arg length - got 0, expected 8". perl5 reads
  the length of a string that is not there: undef segfaults, and the
  others report a number from memory ("got 94515720394056").

## Modules

- [`IO::Tty::Constant`](Tty/Constant.md) - Terminal Constants (autogenerated)

## Functions

### Pseudo-terminals

#### [`ttyname`](Tty/ttyname)

The name of the terminal a handle is open on, or undef.

#### [`pack_winsize`](Tty/pack_winsize)

A `struct winsize` as a string, for the TIOCSWINSZ `ioctl`.

#### `unpack_winsize`

The four numbers of a `struct winsize` string.

**Synopsis**

```perl
my ($rows, $cols, $xpixel, $ypixel) = IO::Tty::unpack_winsize($ws);
```

**What you get back**

Four numbers; a string that is not eight bytes long dies
"IO::Tty::unpack_winsize(): Bad arg length - got N, expected 8".

```{toctree}
:hidden:
:maxdepth: 1

Tty/Constant
Tty/ttyname
Tty/pack_winsize
```