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 });

 Upgrading STDIN/STDOUT/STDERR

    If you pass the -upgrade option at import time, any of STDIN, STDOUT or
    STDERR that are found to be TTY wrappers are automatically upgraded
    into IO::Termios instances.

       use IO::Termios -upgrade;
    
       STDIN->setflag_echo(0);

 Arbitrary Baud Rates on Linux

    Linux supports a non-POSIX extension to the usual termios interface,
    which allows arbitrary baud rates to be set. IO::Termios 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 set*baud methods to set any rate allowed by the
    kernel/driver. If not, then only the POSIX-compatible rates may be
    used.

CONSTRUCTORS

 new

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

 new (handle)

       $term = IO::Termios->new( $handle );

    Construct a new IO::Termios object around the given filehandle.

 open

       $term = IO::Termios->open( $path, $modestr, $flags );

    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.

    If $flags is provided, it will be passed on to the underlying sysopen()
    call used to open the filehandle. It should contain a bitwise-or
    combination of O_* flags from the Fcntl module - for example O_NOCTTY
    or O_NDELAY. The value O_RDWR will be added to this; the caller does
    not need to specify it directly. For example:

       use Fcntl qw( O_NOCTTY O_NDELAY );
    
       $term = IO::Termios->open( "/dev/ttyS0", O_NOCTTY|O_NDELAY );
       $term->setflag_clocal( 1 );
       $term->blocking( 1 );

METHODS

 getattr

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

 setattr

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

 set_mode

 get_mode

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

 tiocmget

 tiocmset

       $bits = $term->tiocmget;
    
       $term->tiocmset( $bits );

    Accessor for the modem line control bits. Takes or returns a bitmask of
    values.

 tiocmbic

 tiocmbis

       $term->tiocmbic( $bits );
    
       $term->tiocmbis( $bits );

    Bitwise mutator methods for the modem line control bits. tiocmbic will
    clear just the bits provided and leave the others unchanged; tiocmbis
    will set them.

 get_modem

       $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

 set_modem

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

 getmodem_BIT

 setmodem_BIT

       $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" );

 getibaud

 getobaud

 setibaud

 setobaud

 setbaud

       $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 Bnnn constants.

 getcsize

 setcsize

       $bits = $term->getcsize;
    
       $term->setcsize( $bits );

    Convenience accessor for the CSIZE bits of c_cflag. $bits is an integer
    5 to 8.

 getparity

 setparity

       $parity = $term->getparity;
    
       $term->setparity( $parity );

    Convenience accessor for the PARENB and PARODD bits of c_cflag. $parity
    is n, o or e.

 getstop

 setstop

       $stop = $term->getstop;
    
       $term->setstop( $stop );

    Convenience accessor for the CSTOPB bit of c_cflag. $stop is 1 or 2.

 cfmakeraw

       $term->cfmakeraw;

    Since version 0.07.

    Adjusts several bit flags to put the terminal into a "raw" mode. Input
    is available a character at a time, echo is disabled, and all special
    processing of input and output characters is disabled.

 getflag_FLAG

 setflag_FLAG

       $mode = $term->getflag_FLAG;
    
       $term->setflag_FLAG( $mode );

    Accessors for various control flags. The following methods are defined
    for specific flags:

  inlcr

    Since version 0.09.

    The INLCR bit of the c_iflag. This translates NL to CR on input.

  igncr

    Since version 0.09.

    The IGNCR bit of the c_iflag. This ignores incoming CR characters.

  icrnl

    Since version 0.09.

    The ICRNL bit of the c_iflag. This translates CR to NL on input, unless
    IGNCR is also set.

  ignbrk

    Since version 0.09.

    The IGNBRK bit of the c_iflag. This controls whether incoming break
    conditions are ignored entirely.

  brkint

    Since version 0.09.

    The BRKINT bit of the c_iflag. This controls whether non-ignored
    incoming break conditions result in a SIGINT signal being delivered to
    the process. If not, such a condition reads as a nul byte.

  parmrk

    Since version 0.09.

    The PARMRK bit of the c_iflag. This controls how parity errors and
    break conditions are handled.

  opost

    Since version 0.07.

    The OPOST bit of the c_oflag. This enables system-specific
    post-processing on output.

  cread

    The CREAD bit of the c_cflag. This enables the receiver.

  hupcl

    The HUPCL bit of the c_cflag. This lowers the modem control lines after
    the last process closes the device.

  clocal

    The CLOCAL bit of the c_cflag. This controls whether local mode is
    enabled; which if set, ignores modem control lines.

  icanon

    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 true), or if individual bytes from keystrokes will be
    returned as they are available (if false).

  echo

    The ECHO bit of c_lflag. This controls whether input characters are
    echoed back to the terminal.

 setflags

       $term->setflags( @flags );

    Since version 0.09.

    A convenient wrapper to calling multiple flag setting methods in a
    sequence.

    Each flag is specified by name, in lower case, prefixed by either a +
    symbol to enable it, or - to disable. For example:

       $term->setflags( "+igncr", "+opost", "+clocal", "-echo" );

TODO

      * Adding more getflag_*/setflag_* convenience wrappers

SEE ALSO

      * IO::Tty - Import Tty control constants

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>