NAME
    `IO::Termios' - supply termios(3) methods to `IO::Handle' objects

SYNOPSIS
     use IO::Termios;

     my $term = IO::Termios->open( "/dev/ttyS0", "9600,8,n,1" )
        or die "Cannot open ttyS0 - $!";

     $term->print( "Hello world\n" ); # Still an IO::Handle

     while( <$term> ) {
        print "A line from ttyS0: $_";
     }

DESCRIPTION
    This class extends the generic `IO::Handle' object class by providing
    methods which access the system's terminal control `termios(3)'
    operations. These methods are primarily of interest when dealing with
    TTY devices, including serial ports.

    The flag-setting methods will apply to any TTY device, such as a
    pseudo-tty, and are useful for controlling such flags as the `ECHO'
    flag, to disable local echo.

     my $stdin = IO::Termios->new( \*STDIN );
     $stdin->setflag_echo( 0 );

    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.

     my $ttyS0 = IO::Termios->open( "/dev/ttyS0" );
     $ttyS0->set_mode( "19200,8,n,1" );
     $ttyS0->set_modem({ dsr => 1, cts => 1 });

CONSTRUCTORS
  $term = IO::Termios->new()
    Construct a new `IO::Termios' object around the terminal for the
    program. This is found by checking if any of `STDIN', `STDOUT' or
    `STDERR' are a terminal. The first one that's found is used. An error
    occurs if no terminal can be found by this method.

  $term = IO::Termios->new( $handle )
    Construct a new `IO::Termios' object around the given filehandle.

  $term = IO::Termios->open( $path, $modestr )
    Open the given path, and return a new `IO::Termios' object around the
    filehandle. If the `open' call fails, `undef' is returned.

    If `$modestr' is provided, the constructor will pass it to the
    `set_mode' method before returning.

METHODS
  $attrs = $term->getattr
    Makes a `tcgetattr()' call on the underlying filehandle, and returns a
    `IO::Termios::Attrs' object.

    If the `tcgetattr()' call fails, `undef' is returned.

  $term->setattr( $attrs )
    Makes a `tcsetattr()' call on the underlying file handle, setting
    attributes from the given `IO::Termios::Attrs' object.

    If the `tcsetattr()' call fails, `undef' is returned. Otherwise, a true
    value is returned.

  $term->set_mode( $modestr )
  $modestr = $term->get_mode
    Accessor for the derived "mode string", which is a comma-joined
    concatenation of the baud rate, character size, parity mode, and stop
    size in a format such as

     19200,8,n,1

    When setting the mode string, trailing components may be omitted meaning
    their value will not be affected.

  $bits = $term->tiocmget
  $term->tiocmset( $bits )
    Accessor for the modem line control bits. Takes or returns a bitmask of
    values.

  $term->tiombic( $bits )
  $term->tiombis( $bits )
    Bitwise mutator methods for the modem line control bits. `tiombic' will
    clear just the bits provided and leave the others unchanged; `tiombis'
    will set them.

  $flags = $term->get_modem
    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

     dtr dsr rts cts cd ri

  $term->set_modem( $flags )
    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 `$flags'
    hash of the names given above. False values will be cleared, true values
    will be set. Other flags will not be altered.

  $set = $term->getmodem_BIT
  $term->setmodem_BIT( $set )
    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.

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.

    For efficiency, when getting or setting a large number of flags, it may
    be more efficient to call `getattr', then operate on the returned
    object, before possibly passing it to `setattr'. The returned
    `IO::Termios::Attrs' object supports the same methods as documented
    here.

    The following two sections of code are therefore equivalent, though the
    latter is more efficient as it only calls `setattr' once.

     $term->setbaud( 38400 );
     $term->setcsize( 8 );
     $term->setparity( 'n' );
     $term->setstop( 1 );



     my $attrs = $term->getattr;
     $attrs->setbaud( 38400 );
     $attrs->setcsize( 8 );
     $attrs->setparity( 'n' );
     $attrs->setstop( 1 );
     $term->setattr( $attrs );

    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 `set_mode':

     $term->set_mode( "38400,8,n,1" );

  $baud = $term->getibaud
  $baud = $term->getobaud
  $term->setibaud( $baud )
  $term->setobaud( $baud )
  $term->setbaud( $baud )
    Convenience accessors for the `ispeed' and `ospeed'. `$baud' is an
    integer directly giving the line rate, instead of one of the `B*nnn*'
    constants.

  $bits = $term->getcsize
  $term->setcsize( $bits )
    Convenience accessor for the `CSIZE' bits of `c_cflag'. `$bits' is an
    integer 5 to 8.

  $parity = $term->getparity
  $term->setparity( $parity )
    Convenience accessor for the `PARENB' and `PARODD' bits of `c_cflag'.
    `$parity' is `n', `o' or `e'.

  $stop = $term->getstop
  $term->setstop( $stop )
    Convenience accessor for the `CSTOPB' bit of `c_cflag'. `$stop' is 1 or
    2.

  $mode = $term->getflag_cread
  $term->setflag_cread( $mode )
    Accessor for the `CREAD' bit of the `c_cflag'. This enables the
    receiver.

  $mode = $term->getflag_hupcl
  $term->setflag_hupcl( $mode )
    Accessor for the `HUPCL' bit of the `c_cflag'. This lowers the modem
    control lines after the last process closes the device.

  $mode = $term->getflag_clocal
  $term->setflag_clocal( $mode )
    Accessor for the `CLOCAL' bit of the `c_cflag'. This controls whether
    local mode is enabled; which if set, ignores modem control lines.

  $mode = $term->getflag_icanon
  $term->setflag_icanon( $mode )
    Accessor for the `ICANON' bit of `c_lflag'. This is called "canonical"
    mode and controls whether the terminal's line-editing feature will be
    used to return a whole line (if false), or if individual bytes from
    keystrokes will be returned as they are available (if true).

  $mode = $term->getflag_echo
  $term->setflag_echo( $mode )
    Accessor for the `ECHO' bit of `c_lflag'. This controls whether input
    characters are echoed back to the terminal.

TODO
    *   Adding more getflag_*/setflag_* convenience wrappers

    *   Automatically upgrading STDIN/STDOUT/STDERR if appropriate, given a
        flag.

         use IO::Termios -upgrade;

         STDIN->setflag_echo( 0 );

SEE ALSO
    *   IO::Tty - Import Tty control constants

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

