=encoding utf8

=head1 NAME

POSIX::1003::Termios - POSIX general terminal interface

=head1 SYNOPSIS

  use POSIX::1003::Termios qw(:speed);
  $termios = POSIX::1003::Termios->new;
  $ispeed = $termios->getispeed;
  $termios->setospeed(B9600);

  use POSIX::1003::Termios qw(:functions :actions);
  tcsendbreak($fd, $duration);
  tcflush($fd, TCIFLUSH);

  $tty  = ttyname($fd);
  $tty  = ttyname($fh->fileno);

=head1 DESCRIPTION

This module provides an interface to the "General Terminal Interfaces",
as specified by POSIX. The actual implementation is part of POSIX.xs

=head1 METHODS

=head2 Constructors

=over 4

=item POSIX::1003::Termios-E<gt>B<new>()

Create a new Termios object. This object will be destroyed automatically
when it is no longer needed. A Termios object corresponds to the
termios C struct.

  $termios = POSIX::1003::Termios->new;

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<getattr>( [$fd] )

Get terminal control attributes (POSIX function C<tcgetattr>). Pass a file
descriptor, which defaults to C<0> (stdin). Returns C<undef> on failure.

  # Obtain the attributes for stdin
  $termios->getattr(0);
  $termios->getattr();

  # Obtain the attributes for stdout
  $termios->getattr(1);

=item $obj-E<gt>B<getcc>($index)

Retrieve a value from the C<c_cc> field of a termios object. The c_cc field is
an array so an index must be specified.
  $c_cc[1] = $termios->getcc(1);

=item $obj-E<gt>B<getcflag>()

Retrieve the C<c_cflag> field of a termios object.
  $c_cflag = $termios->getcflag;

=item $obj-E<gt>B<getiflag>()

Retrieve the C<c_iflag> field of a termios object.
  $c_iflag = $termios->getiflag;

=item $obj-E<gt>B<getispeed>()

Retrieve the input baud rate.
  $ispeed = $termios->getispeed;

=item $obj-E<gt>B<getlflag>()

Retrieve the C<c_lflag> field of a termios object.
  $c_lflag = $termios->getlflag;

=item $obj-E<gt>B<getoflag>()

Retrieve the C<c_oflag> field of a termios object.
  $c_oflag = $termios->getoflag;

=item $obj-E<gt>B<getospeed>()

Retrieve the output baud rate.
  $ospeed = $termios->getospeed;

=item $obj-E<gt>B<setattr>($fd, $flags)

Set terminal control attributes (POSIX function C<tcsetattr>).  Returns
C<undef> on failure.

  # Set attributes immediately for stdout.
  $termios->setattr(1, TCSANOW);

=item $obj-E<gt>B<setcc>($value, $index)

Set a value in the C<c_cc> field of a termios object.  The c_cc field is an
array so an index must be specified.
  $termios->setcc(VEOF, 1 );

=item $obj-E<gt>B<setcflag>($flags)

Set the C<c_cflag> field of a termios object.
  $termios->setcflag( $c_cflag | CLOCAL );

=item $obj-E<gt>B<setiflag>($flags)

Set the C<c_iflag> field of a termios object.
  $termios->setiflag( $c_iflag | BRKINT );

=item $obj-E<gt>B<setispeed>()

Set the input baud rate.  Returns C<undef> on failure.
  $termios->setispeed( B9600 );

=item $obj-E<gt>B<setlflag>($flags)

Set the C<c_lflag> field of a termios object.
  $termios->setlflag( $c_lflag | ECHO );

=item $obj-E<gt>B<setoflag>($flags)

Set the c_oflag field of a termios object.
  $termios->setoflag( $c_oflag | OPOST );

=item $obj-E<gt>B<setospeed>()

Set the output baud rate.
  $termios->setospeed( B9600 );

=back

=head1 FUNCTIONS

=over 4

=item B<tcdrain>($fd)

=item B<tcflow>($fd, $action)

See the possible $action values in L</CONSTANTS>, import tag C<:action>

=item B<tcflush>($fd, $queue)

See the possible $queue values in L</CONSTANTS>, import tag C<:flush>

=item B<tcsendbreak>($fd, $duration)

$duration is system dependent.

=item B<ttyname>($fd)

Returns the path to the special device which relates to the file-descriptor.
See also L<POSIX::1003::Proc::ctermid()|POSIX::1003::Proc/"Standard POSIX functions from unistd.h">

  $tty  = ttyname($fd);
  $tty  = ttyname($fh->fileno);

=back

=head1 CONSTANTS

=over 4

=item Available baudrates (ispeed and ospeed), export tag C<:speed>.

  B0 B50 B75 B110 B134 B150 B200 B300 B600 B1200
  B1800 B2400 B4800 B9600 B19200 B38400

=item Interface values (getattr and setattr), export tag C<:actions>.

  TCSADRAIN TCSANOW TCOON TCION TCSAFLUSH TCIOFF TCOOFF

=item To be used as L<tcflush()|POSIX::1003::Termios/"FUNCTIONS"> parameter QUEUE

  TCIOFLUSH TCOFLUSH TCIFLUSH

=item c_cc field values, export tag C<:flags> as have all following constants.

  VEOF VEOL VERASE VINTR VKILL VQUIT VSUSP VSTART VSTOP VMIN
  VTIME NCCS

=item c_cflag field values

  CLOCAL CREAD CSIZE CS5 CS6 CS7 CS8 CSTOPB HUPCL PARENB PARODD

=item c_iflag field values

  BRKINT ICRNL IGNBRK IGNCR IGNPAR INLCR INPCK ISTRIP IXOFF
  IXON PARMRK

=item c_lflag field values

  ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH TOSTOP

=item c_oflag field values

  OPOST

=back

All constants, shown here with the values discovered during installation
of this module:

=for comment
#TABLE_TERMIOS_START

  During installation, a symbol table will get inserted here.

=for comment
#TABLE_TERMIOS_END

=head1 SEE ALSO

This module is part of POSIX-1003 distribution version 1.02,
built on November 10, 2020. Website: F<http://perl.overmeer.net/CPAN>.  The code is based on L<POSIX>, which
is released with Perl itself.  See also L<POSIX::Util> for
additional functionality.

=head1 COPYRIGHTS

Copyrights 2011-2020 on the perl code and the related documentation
 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>

