.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "IO::Termios 3pm"
.TH IO::Termios 3pm "2023-01-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"IO::Termios" \- supply termios(3) methods to "IO::Handle" objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use IO::Termios;
\&
\&   my $term = IO::Termios\->open( "/dev/ttyS0", "9600,8,n,1" )
\&      or die "Cannot open ttyS0 \- $!";
\&
\&   $term\->print( "Hello world\en" ); # Still an IO::Handle
\&
\&   while( <$term> ) {
\&      print "A line from ttyS0: $_";
\&   }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class extends the generic \f(CW\*(C`IO::Handle\*(C'\fR object class by providing methods
which access the system's terminal control \f(CWtermios(3)\fR operations. These
methods are primarily of interest when dealing with \s-1TTY\s0 devices, including
serial ports.
.PP
The flag-setting methods will apply to any \s-1TTY\s0 device, such as a pseudo-tty,
and are useful for controlling such flags as the \f(CW\*(C`ECHO\*(C'\fR flag, to disable
local echo.
.PP
.Vb 2
\&   my $stdin = IO::Termios\->new( \e*STDIN );
\&   $stdin\->setflag_echo( 0 );
.Ve
.PP
When dealing with a serial port the line mode method is useful for setting the
basic serial parameters such as baud rate, and the modem line control methods
can be used to access the hardware handshaking lines.
.PP
.Vb 3
\&   my $ttyS0 = IO::Termios\->open( "/dev/ttyS0" );
\&   $ttyS0\->set_mode( "19200,8,n,1" );
\&   $ttyS0\->set_modem({ dsr => 1, cts => 1 });
.Ve
.SS "Upgrading \s-1STDIN/STDOUT/STDERR\s0"
.IX Subsection "Upgrading STDIN/STDOUT/STDERR"
If you pass the \f(CW\*(C`\-upgrade\*(C'\fR option at \f(CW\*(C`import\*(C'\fR time, any of \s-1STDIN, STDOUT\s0 or
\&\s-1STDERR\s0 that are found to be \s-1TTY\s0 wrappers are automatically upgraded into
\&\f(CW\*(C`IO::Termios\*(C'\fR instances.
.PP
.Vb 1
\&   use IO::Termios \-upgrade;
\&
\&   STDIN\->setflag_echo(0);
.Ve
.SS "Arbitrary Baud Rates on Linux"
.IX Subsection "Arbitrary Baud Rates on Linux"
\&\fILinux\fR supports a non-POSIX extension to the usual \f(CW\*(C`termios\*(C'\fR interface,
which allows arbitrary baud rates to be set. \f(CW\*(C`IO::Termios\*(C'\fR can automatically
make use of this ability if the Linux::Termios2 module is installed. If so,
this will be used automatically and transparently, to allow the \f(CW\*(C`set*baud\*(C'\fR
methods to set any rate allowed by the kernel/driver. If not, then only the
POSIX-compatible rates may be used.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&   $term = IO::Termios\->new()
.Ve
.PP
Construct a new \f(CW\*(C`IO::Termios\*(C'\fR object around the terminal for the program.
This is found by checking if any of \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR or \f(CW\*(C`STDERR\*(C'\fR are a
terminal. The first one that's found is used. An error occurs if no terminal
can be found by this method.
.SS "new (handle)"
.IX Subsection "new (handle)"
.Vb 1
\&   $term = IO::Termios\->new( $handle )
.Ve
.PP
Construct a new \f(CW\*(C`IO::Termios\*(C'\fR object around the given filehandle.
.SS "open"
.IX Subsection "open"
.Vb 1
\&   $term = IO::Termios\->open( $path, $modestr, $flags )
.Ve
.PP
Open the given path, and return a new \f(CW\*(C`IO::Termios\*(C'\fR object around the
filehandle. If the \f(CW\*(C`open\*(C'\fR call fails, \f(CW\*(C`undef\*(C'\fR is returned.
.PP
If \f(CW$modestr\fR is provided, the constructor will pass it to the \f(CW\*(C`set_mode\*(C'\fR
method before returning.
.PP
If \f(CW$flags\fR is provided, it will be passed on to the underlying \f(CW\*(C`sysopen()\*(C'\fR
call used to open the filehandle. It should contain a bitwise-or combination
of \f(CW\*(C`O_*\*(C'\fR flags from the Fcntl module \- for example \f(CW\*(C`O_NOCTTY\*(C'\fR or
\&\f(CW\*(C`O_NDELAY\*(C'\fR. The value \f(CW\*(C`O_RDWR\*(C'\fR will be added to this; the caller does not
need to specify it directly. For example:
.PP
.Vb 1
\&   use Fcntl qw( O_NOCTTY O_NDELAY );
\&
\&   $term = IO::Termios\->open( "/dev/ttyS0", O_NOCTTY|O_NDELAY );
\&   $term\->setflag_clocal( 1 );
\&   $term\->blocking( 1 );
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "getattr"
.IX Subsection "getattr"
.Vb 1
\&   $attrs = $term\->getattr
.Ve
.PP
Makes a \f(CW\*(C`tcgetattr()\*(C'\fR call on the underlying filehandle, and returns a
\&\f(CW\*(C`IO::Termios::Attrs\*(C'\fR object.
.PP
If the \f(CW\*(C`tcgetattr()\*(C'\fR call fails, \f(CW\*(C`undef\*(C'\fR is returned.
.SS "setattr"
.IX Subsection "setattr"
.Vb 1
\&   $term\->setattr( $attrs )
.Ve
.PP
Makes a \f(CW\*(C`tcsetattr()\*(C'\fR call on the underlying file handle, setting attributes
from the given \f(CW\*(C`IO::Termios::Attrs\*(C'\fR object.
.PP
If the \f(CW\*(C`tcsetattr()\*(C'\fR call fails, \f(CW\*(C`undef\*(C'\fR is returned. Otherwise, a true
value is returned.
.SS "set_mode"
.IX Subsection "set_mode"
.SS "get_mode"
.IX Subsection "get_mode"
.Vb 1
\&   $term\->set_mode( $modestr )
\&
\&   $modestr = $term\->get_mode
.Ve
.PP
Accessor for the derived \*(L"mode string\*(R", which is a comma-joined concatenation
of the baud rate, character size, parity mode, and stop size in a format such
as
.PP
.Vb 1
\&   19200,8,n,1
.Ve
.PP
When setting the mode string, trailing components may be omitted meaning their
value will not be affected.
.SS "tiocmget"
.IX Subsection "tiocmget"
.SS "tiocmset"
.IX Subsection "tiocmset"
.Vb 1
\&   $bits = $term\->tiocmget
\&
\&   $term\->tiocmset( $bits )
.Ve
.PP
Accessor for the modem line control bits. Takes or returns a bitmask of
values.
.SS "tiocmbic"
.IX Subsection "tiocmbic"
.SS "tiocmbis"
.IX Subsection "tiocmbis"
.Vb 1
\&   $term\->tiocmbic( $bits )
\&
\&   $term\->tiocmbis( $bits )
.Ve
.PP
Bitwise mutator methods for the modem line control bits. \f(CW\*(C`tiocmbic\*(C'\fR will
clear just the bits provided and leave the others unchanged; \f(CW\*(C`tiocmbis\*(C'\fR will
set them.
.SS "get_modem"
.IX Subsection "get_modem"
.Vb 1
\&   $flags = $term\->get_modem
.Ve
.PP
Returns a hash reference containing named flags corresponding to the modem
line control bits. Any bit that is set will yield a key in the returned hash
of the same name. The bit names are
.PP
.Vb 1
\&   dtr dsr rts cts cd ri
.Ve
.SS "set_modem"
.IX Subsection "set_modem"
.Vb 1
\&   $term\->set_modem( $flags )
.Ve
.PP
Changes the modem line control bit flags as given by the hash reference. Each
bit to be changed should be represented by a key in the \f(CW$flags\fR hash of the
names given above. False values will be cleared, true values will be set.
Other flags will not be altered.
.SS "getmodem_BIT"
.IX Subsection "getmodem_BIT"
.SS "setmodem_BIT"
.IX Subsection "setmodem_BIT"
.Vb 1
\&   $set = $term\->getmodem_BIT
\&
\&   $term\->setmodem_BIT( $set )
.Ve
.PP
Accessor methods for each of the modem line control bits. A set of methods
exists for each of the named modem control bits given above.
.SH "FLAG-ACCESSOR METHODS"
.IX Header "FLAG-ACCESSOR METHODS"
Theses methods are implemented in terms of the lower level methods, but
provide an interface which is more abstract, and easier to re-implement on
other non-POSIX systems. These should be used in preference to the lower ones.
.PP
For efficiency, when getting or setting a large number of flags, it may be
more efficient to call \f(CW\*(C`getattr\*(C'\fR, then operate on the returned object,
before possibly passing it to \f(CW\*(C`setattr\*(C'\fR. The returned \f(CW\*(C`IO::Termios::Attrs\*(C'\fR
object supports the same methods as documented here.
.PP
The following two sections of code are therefore equivalent, though the latter
is more efficient as it only calls \f(CW\*(C`setattr\*(C'\fR once.
.PP
.Vb 4
\&   $term\->setbaud( 38400 );
\&   $term\->setcsize( 8 );
\&   $term\->setparity( \*(Aqn\*(Aq );
\&   $term\->setstop( 1 );
.Ve
.PP

.PP
.Vb 6
\&   my $attrs = $term\->getattr;
\&   $attrs\->setbaud( 38400 );
\&   $attrs\->setcsize( 8 );
\&   $attrs\->setparity( \*(Aqn\*(Aq );
\&   $attrs\->setstop( 1 );
\&   $term\->setattr( $attrs );
.Ve
.PP
However, a convenient shortcut method is provided for the common case of
setting the baud rate, character size, parity and stop size all at the same
time. This is \f(CW\*(C`set_mode\*(C'\fR:
.PP
.Vb 1
\&   $term\->set_mode( "38400,8,n,1" );
.Ve
.SS "getibaud"
.IX Subsection "getibaud"
.SS "getobaud"
.IX Subsection "getobaud"
.SS "setibaud"
.IX Subsection "setibaud"
.SS "setobaud"
.IX Subsection "setobaud"
.SS "setbaud"
.IX Subsection "setbaud"
.Vb 1
\&   $baud = $term\->getibaud
\&
\&   $baud = $term\->getobaud
\&
\&   $term\->setibaud( $baud )
\&
\&   $term\->setobaud( $baud )
\&
\&   $term\->setbaud( $baud )
.Ve
.PP
Convenience accessors for the \f(CW\*(C`ispeed\*(C'\fR and \f(CW\*(C`ospeed\*(C'\fR. \f(CW$baud\fR is an integer
directly giving the line rate, instead of one of the \f(CW\*(C`B\f(CInnn\f(CW\*(C'\fR constants.
.SS "getcsize"
.IX Subsection "getcsize"
.SS "setcsize"
.IX Subsection "setcsize"
.Vb 1
\&   $bits = $term\->getcsize
\&
\&   $term\->setcsize( $bits )
.Ve
.PP
Convenience accessor for the \f(CW\*(C`CSIZE\*(C'\fR bits of \f(CW\*(C`c_cflag\*(C'\fR. \f(CW$bits\fR is an
integer 5 to 8.
.SS "getparity"
.IX Subsection "getparity"
.SS "setparity"
.IX Subsection "setparity"
.Vb 1
\&   $parity = $term\->getparity
\&
\&   $term\->setparity( $parity )
.Ve
.PP
Convenience accessor for the \f(CW\*(C`PARENB\*(C'\fR and \f(CW\*(C`PARODD\*(C'\fR bits of \f(CW\*(C`c_cflag\*(C'\fR.
\&\f(CW$parity\fR is \f(CW\*(C`n\*(C'\fR, \f(CW\*(C`o\*(C'\fR or \f(CW\*(C`e\*(C'\fR.
.SS "getstop"
.IX Subsection "getstop"
.SS "setstop"
.IX Subsection "setstop"
.Vb 1
\&   $stop = $term\->getstop
\&
\&   $term\->setstop( $stop )
.Ve
.PP
Convenience accessor for the \f(CW\*(C`CSTOPB\*(C'\fR bit of \f(CW\*(C`c_cflag\*(C'\fR. \f(CW$stop\fR is 1 or 2.
.SS "cfmakeraw"
.IX Subsection "cfmakeraw"
.Vb 1
\&   $term\->cfmakeraw
.Ve
.PP
\&\fISince version 0.07.\fR
.PP
Adjusts several bit flags to put the terminal into a \*(L"raw\*(R" mode. Input is
available a character at a time, echo is disabled, and all special processing
of input and output characters is disabled.
.SS "getflag_\fI\s-1FLAG\s0\fP"
.IX Subsection "getflag_FLAG"
.SS "setflag_\fI\s-1FLAG\s0\fP"
.IX Subsection "setflag_FLAG"
.Vb 1
\&   $mode = $term\->getflag_FLAG
\&
\&   $term\->setflag_FLAG( $mode )
.Ve
.PP
Accessors for various control flags. The following methods are defined for
specific flags:
.PP
\fIinlcr\fR
.IX Subsection "inlcr"
.PP
\&\fISince version 0.09.\fR
.PP
The \f(CW\*(C`INLCR\*(C'\fR bit of the \f(CW\*(C`c_iflag\*(C'\fR. This translates \s-1NL\s0 to \s-1CR\s0 on input.
.PP
\fIigncr\fR
.IX Subsection "igncr"
.PP
\&\fISince version 0.09.\fR
.PP
The \f(CW\*(C`IGNCR\*(C'\fR bit of the \f(CW\*(C`c_iflag\*(C'\fR. This ignores incoming \s-1CR\s0 characters.
.PP
\fIicrnl\fR
.IX Subsection "icrnl"
.PP
\&\fISince version 0.09.\fR
.PP
The \f(CW\*(C`ICRNL\*(C'\fR bit of the \f(CW\*(C`c_iflag\*(C'\fR. This translates \s-1CR\s0 to \s-1NL\s0 on input, unless
\&\f(CW\*(C`IGNCR\*(C'\fR is also set.
.PP
\fIignbrk\fR
.IX Subsection "ignbrk"
.PP
\&\fISince version 0.09.\fR
.PP
The \f(CW\*(C`IGNBRK\*(C'\fR bit of the \f(CW\*(C`c_iflag\*(C'\fR. This controls whether incoming break
conditions are ignored entirely.
.PP
\fIbrkint\fR
.IX Subsection "brkint"
.PP
\&\fISince version 0.09.\fR
.PP
The \f(CW\*(C`BRKINT\*(C'\fR bit of the \f(CW\*(C`c_iflag\*(C'\fR. This controls whether non-ignored
incoming break conditions result in a \f(CW\*(C`SIGINT\*(C'\fR signal being delivered to the
process. If not, such a condition reads as a nul byte.
.PP
\fIparmrk\fR
.IX Subsection "parmrk"
.PP
\&\fISince version 0.09.\fR
.PP
The \f(CW\*(C`PARMRK\*(C'\fR bit of the \f(CW\*(C`c_iflag\*(C'\fR. This controls how parity errors and break
conditions are handled.
.PP
\fIopost\fR
.IX Subsection "opost"
.PP
\&\fISince version 0.07.\fR
.PP
The \f(CW\*(C`OPOST\*(C'\fR bit of the \f(CW\*(C`c_oflag\*(C'\fR. This enables system-specific
post-processing on output.
.PP
\fIcread\fR
.IX Subsection "cread"
.PP
The \f(CW\*(C`CREAD\*(C'\fR bit of the \f(CW\*(C`c_cflag\*(C'\fR. This enables the receiver.
.PP
\fIhupcl\fR
.IX Subsection "hupcl"
.PP
The \f(CW\*(C`HUPCL\*(C'\fR bit of the \f(CW\*(C`c_cflag\*(C'\fR. This lowers the modem control lines after
the last process closes the device.
.PP
\fIclocal\fR
.IX Subsection "clocal"
.PP
The \f(CW\*(C`CLOCAL\*(C'\fR bit of the \f(CW\*(C`c_cflag\*(C'\fR. This controls whether local mode is
enabled; which if set, ignores modem control lines.
.PP
\fIicanon\fR
.IX Subsection "icanon"
.PP
The \f(CW\*(C`ICANON\*(C'\fR bit of \f(CW\*(C`c_lflag\*(C'\fR. This is called \*(L"canonical\*(R" mode and controls
whether the terminal's line-editing feature will be used to return a whole
line (if true), or if individual bytes from keystrokes will be returned as
they are available (if false).
.PP
\fIecho\fR
.IX Subsection "echo"
.PP
The \f(CW\*(C`ECHO\*(C'\fR bit of \f(CW\*(C`c_lflag\*(C'\fR. This controls whether input characters are
echoed back to the terminal.
.SS "setflags"
.IX Subsection "setflags"
.Vb 1
\&   $term\->setflags( @flags )
.Ve
.PP
\&\fISince version 0.09.\fR
.PP
A convenient wrapper to calling multiple flag setting methods in a sequence.
.PP
Each flag is specified by name, in lower case, prefixed by either a \f(CW\*(C`+\*(C'\fR
symbol to enable it, or \f(CW\*(C`\-\*(C'\fR to disable. For example:
.PP
.Vb 1
\&   $term\->setflags( "+igncr", "+opost", "+clocal", "\-echo" );
.Ve
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Adding more getflag_*/setflag_* convenience wrappers
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
IO::Tty \- Import Tty control constants
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>