*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> ldterm (7)              
Title
Content
Arch
Section
 

o(7)

Contents


 ldterm(7)                                                         ldterm(7)




 NAME    [Toc]    [Back]
      ldterm - standard STREAMS terminal line discipline module

 SYNOPSIS    [Toc]    [Back]
      #include <sys/stream.h>
      #include <sys/stropts.h>
      #include <sys/termios.h>
      #include <sys/bsdtty.h>
      #include <sys/ttold.h>
      #include <sys/strtio.h>
      #include <sys/eucioctl.h>

      int ioctl( fd, I_PUSH, "ldterm");

 DESCRIPTION    [Toc]    [Back]
      ldterm is a STREAMS module that supplies the line discipline for
      streams-based terminal or pseudo-terminal device drivers. This module
      provides most of the functions of the general terminal interface
      described in termio(7).  However, it does not perform the low-level
      device control functions specified by the c_cflag word defined by the
      POSIX termios structure or the System V termio structure (defined in
      termios.h and termio.h, respectively).  Also, some operations require
      the cooperation of the modules and drivers pushed below the ldterm
      module in a tty or pty (slave) stream.  This man page only covers
      ldterm specific interface here and refers to the readers to termio(7)
      for the detail terminal interface.

      Internally, the ldterm module uses the Extended UNIX Code (EUC)
      character encoding scheme.  This encoding scheme enables the ldterm
      module to process multibyte characters as well as simple 8-bit
      characters.  It correctly handles backspacing, word erasing, and tab
      expansion for multibyte EUC characters.

      The ldterm module provides standard terminal operation consistent with
      the behavior specified by POSIX 1003.1 and System V Interface
      Definition (SVID) Third Edition.  It also provides compatibility with
      the behavior of the BSD 4.3 line discipline. Notice that on other
      STREAMS systems, the BSD 4.3 compatibility feature is usually provided
      by a separate STREAMS module called ttcompat.  Hence, applications on
      HP-UX need not push ttcompat on top of ldterm to get BSD 4.3
      compatibility.  In fact, the ttcompat module is not provided on the
      HP-UX system at all.

      The ldterm module normally sits above either a STREAMS tty driver or a
      STREAMS pty slave driver. The user issues an STREAMS I_PUSH ioctl(2)
      system call to push ldterm onto the stream once the STREAMS tty or
      STREAMS pty slave device is opened.

    STREAMS Messages    [Toc]    [Back]
      The ldterm module processes various types of STREAMS messages.  The
      line discipline will act on any of the following message types.  Any



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




      others that the module receives, however, are passed onto the next
      module on the stream.

    Read-side Behavior    [Toc]    [Back]
      ldterm processes the following STREAMS messages on its input stream:

      M_FLUSH   If FLUSHR is set, the read put routine flushes the read
                queue, discards characters in the input message buffers, and
                discards any partially buffered multibyte EUC characters.
                Then, it forwards the message upstream.

      M_BREAK   The read put routine processes the message according to
                POSIX rules for processing BREAK events, parity errors, and
                framing errors and signal generation (see termio(7) for
                detail).  If there is no data in the message, the message is
                assumed to represent an input BREAK event, which is
                represented by a framing error with a character value of 0
                (zero).  If there is data in the message, the data value is
                an integer that indicates the occurrence of an input BREAK
                event, or a character received with a parity or framing
                error. The low-order 8 bits of the data value is the byte
                that was read.  If the TTY_PE flag is set in the higherorder
 bits of this integer, then a parity error was
                detected.  If the TTY_FE flag is set in the higher-order
                bits of this integer, a framing error was detected.

                After reading the data value, the read put routine discards
                the message.

      M_DATA    The read put routine processes the message according to the
                POSIX 1003.1 specification, using multibyte processing for
                backspacing, word erasing, and tab expansion as appropriate.

                It generates echo characters and places them in the output
                buffer to be sent downstream to the write queue.  While
                processing incoming data, it scans for START and STOP
                characters and sends M_START, M_STOP messages downstream to
                the write queue, if needed.

                If the total number of buffered input characters is more
                than the high-water mark and IXOFF is set, the read put
                routine sends an M_STOPI message downstream.  When the queue
                reduces its backlog below the low water mark, it sends an
                M_STARTI message downstream.

                If the number of buffered input characters reaches
                MAX_INPUT, and the IMAXBEL flag is set, the read put routine
                discards new input characters and sends a BEL character
                (Ctrl-G) downstream.  If IMAXBEL is not set, it flushes the
                input queue.




 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




                If the ISIG flag is set, the read put routine sends M_PCSIG
                messages upstream when the appropriate signal characters are
                encountered.  Then it discards the characters.

                If a character matching c_cc[VDISCARD] is encountered, and
                the IEXTEN flag is set, the read put routine sends an
                M_FLUSH (FLUSHW) message upstream to flush all write queues.
                The M_FLUSH message is reflected by the stream head and sent
                downstream through all the write queues.

                If the character signifies the logical termination of input,
                the read put routine sends the currently buffered characters
                upstream to the stream head.

                Logical termination of input depends on the state of the
                ICANON flag.  If ICANON is set, the ldterm module is in
                canonical input mode.  In that case, the read put routine
                logically terminates input at the end of a line of input.
                Canonical line termination characters are NEWLINE, EOF, EOL,
                and EOL2.  If ICANON is clear, the ldterm discipline module
                is in noncanonical or raw input mode. In that case, the read
                put routine terminates input when at least VMIN bytes are
                present in the input message buffer or the timer specified
                by VTIME expires (see termio(7) for more details).

      M_IOCACK  If the message acknowledges the POSIX termios TCGETS
                command, the read put routine copies the c_cflag and speeds
                information, which is sent by the console driver downstream,
                from the message into the internal POSIX termios structure.
                Then it copies the internal POSIX termios structure into the
                message.

                If the message acknowledges one of the POSIX termios set
                commands (i.e.  TCSETS, TCSETSW, and TCSETSF) the read put
                routine copies all of the data from the message into the
                internal POSIX termios structure.

                After this processing is done, the read put routine
                determines if the I/O control command was originally a BSD
                4.3 or System V I/O control command that was converted to a
                POSIX termios command by the write service routine.  If so,
                it restores the original data so that the message
                acknowledges the original I/O control command.  Then it
                forwards the message upstream.

      M_CTL     This message was sent by the driver to make special requests
                to ldterm. The structure of M_CTL messages is the same as
                that of M_IOCTL messages.  The M_CTL message block points to
                a message buffer containing an iocblk data structure
                (defined in <sys/stream.h>).  The ioc_cmd member of this
                structure contains a command, just as it does in an M_IOCTL



 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




                message.  The b_cont member of the M_CTL message block
                contains a pointer to an M_DATA message block, which
                contains data associated with the M_CTL message.

                The read put routine processes M_CTL messages containing the
                following commands:

                MC_NO_CANON    [Toc]    [Back]
                     Turn off input processing normally performed on
                     upstream M_DATA messages.  This is for the use of
                     modules or drivers that perform their own input
                     processing such as pseudo-terminal (see ptm(7) and
                     pts(7) ) in REMOTE mode connected to a program that
                     performs the input processing.

                MC_DO_CANON    [Toc]    [Back]
                     Turn on input processing normally performed on upstream
                     M_DATA messages.  This message is sent when the driver
                     want ldterm to exit the REMOTE mode.

    Write-side Behavior    [Toc]    [Back]
      ldterm processes the following STREAMS messages on its output stream.
      Messages not listed here are simply forwarded downstream.

      M_FLUSH   The write put routine flushes the write queue and discards
                any buffered output data.  Then, it forwards the message
                downstream.

      M_DATA    The write service routine processes the data according to
                the POSIX 1003.1 specification output flags.  It sends the
                processed characters downstream to the driver when the
                output queue fills up and all of the data is processed.

      M_IOCTL   The write put routine validates the format of the M_IOCTL
                message and checks for known commands.  If the message
                format is invalid, it turns the M_IOCTL message into an
                M_IOCNAK message, and returns the message upstream.  If the
                I/O control command is not recognized, it forwards the
                M_IOCTL message downstream for processing by other modules.

                The write put routine determines if the command is one that
                must be processed in the proper sequence relative to M_DATA
                messages.  If so, it queues the M_IOCTL message to the write
                queue for later processing by the write service routine.
                Commands that require processing in sequence are:

                TCSETSW, TCSETSF, TCSETAW, TCSETAF, TCSBRK

                Otherwise, the module's write put routine processes the
                command immediately. Detailed descriptions of the preceding
                ioctl commands are provided in the "ioctl Commands"



 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




                subsection, below.

      M_READ    This message is sent by the stream head to notify downstream
                modules when an application has issued a read request and
                there is not enough data queued at the stream head to
                satisfy the request.  The M_READ is sent downstream normally
                when ldterm is operating in non-canonical input mode. If
                VTIME is positive, the write put routine starts an input
                timer.  When the timer expires, it sends all buffered input
                upstream.  Then, it forwards the M_READ message downstream.

    ioctl Commands
      The ldterm module acts on two categories of ioctl commands:

           +    Primary terminal I/O control commands

           +    BSD 4.3 compatibility terminal I/O control commands

      Detail descriptions on how to use these ioctls can be found on the
      termi
      are currently not supported on ldterm.

    Primary Terminal I/O Control Commands
      The ldterm module acts on the following primary terminal I/O commands:

      TCSETS, TCSETSW, TCSETSF
                When the ldterm module receives any of these commands in an
                M_IOCTL message, it forwards them downstream.  When it
                receives the M_IOCACK message in the read queue, it copies
                the POSIX termios information from the message into the
                internal POSIX termios structure and forwards the message
                upstream.  If a mode change requires options at the stream
                head to be changed, an M_SETOPTS message is sent upstream.
                If the ICANON flag is turned on or off, the read mode at the
                stream head is changed to message-nondiscard (RMSGN) with
                read notification on (SO_MREADON) or byte-stream mode
                (RNORM) with read notification off (SO_MREADOFF),
                respectively.  If the TOSTOP flag is turned on or off, the
                tostop mode at the stream head is turned on (SO_TOSTOP) or
                off (SO_TONSTOP), respectively.

      TCGETS    The ldterm module forwards the M_IOCTL message downstream.
                When it receives the M_IOCACK message in the read queue, it
                copies the CLOCAL flags and speeds from the message into the
                internal POSIX termios structure.  Then, it copies the
                entire structure into the M_IOCACK message and forwards the
                message upstream.

      TCSETA, TCSETAW, TCSETAF
                These commands set the old System V termio information.  The
                ldterm module converts the message to a POSIX termios



 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




                M_IOCTL message, then forwards the message with a
                corresponding POSIX termios command (i.e.  TCSETS, TCSETSW,
                TCSETSF).  The original I/O control command and M_IOCTL
                message are stored for use on M_IOCACK.

      TCGETA    This command get the old System V termio information.  The
                ldterm module converts the message to a POSIX termios
                M_IOCTL message, then forwards the message with the TCGETS
                command.  The original I/O control command and M_IOCTL
                message are stored to be used on M_IOCACK.  When it receives
                the matching M_IOCACK message, the ldterm module processes
                it as for a TCGETS command, then converts the POSIX termios
                information into the System V termio information and
                replies.

      TCSBRK    The ldterm module forwards this command downstream to be
                handled by the driver so that the driver has a chance to
                drain the data before sending an M_IOCACK message upstream.

      TCXONC    This command controls the behavior of input/output flow
                control.  If the argument is 0 and output is not already
                stopped, an M_STOP message is sent downstream.  If the
                argument is 1 and the output is stopped, an M_START message
                is sent downstream.  If the argument is 2 and input is not
                already stopped, an M_STOPI message is sent downstream.  If
                the argument is 3 and input is stopped, an M_STARTI message
                is sent downstream.

      TCFLSH    This command flush the input or/and output streams.  If the
                argument is 0, an M_FLUSH message with a flag byte of FLUSHR
                is sent downstream.  This M_FLUSH(FLUSHR) message will be
                reflected back upstream by the driver to flush the entire
                input stream.  If the argument is 1, an M_FLUSH message with
                a flag byte of FLUSHW is sent upstream.  This
                M_FLUSH(FLUSHW) message will be reflected downstream by the
                stream head to flush the entire output stream.

      TIOCSWINSZ    [Toc]    [Back]
                This command sets the window size variables. The argument of
                this command takes a pointer to a winsize structure.  The
                ldterm module does not use the window size variable, but
                maintains it here for any needed replies to TIOCGWINSZ
                commands.  The module forwards the message downstream.

      TIOCGWINSZ    [Toc]    [Back]
                When the ldterm module receives this command, it returns the
                window size variable that was set by the last TIOCSWINSZ
                command.  The argument of this command takes a pointer to a
                winsize structure.





 Hewlett-Packard Company            - 6 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




      EUC_WSET  This command sets the character widths and screen widths for
                the EUC character sets.  The argument of this command takes
                a pointer to an eucioc structure which contains the
                information for setting the character widths and screen
                widths of the EUC character sets.  After processing the
                command, ldterm forwards this message downstream to the next
                module.

      EUC_WGET  This command returns the character widths and screen widths
                for the EUC character sets.  This command takes a pointer to
                an eucioc structure via which the EUC character widths and
                screen widths information will be returned.

      EUC_SET_HP15    [Toc]    [Back]
                This command put ldterm to the so called HP15 mode which
                enable ldterm to recognize the HP15_SJIS, HP15_BIG5,
                HP15_CCDC, and HP15_GB character sets and process them in
                such a way that they behave like EUC characters.  The
                argument for this command takes a pointer to an integer
                value which specify on of the above-mentioned four supported
                HP15 character sets.  If the argument is set to HP15_ASCII,
                then ldterm will switch back to normal ASCII processing.
                EUC_WSET is mutually exclusive with EUC_SET_HP15.

      EUC_GET_HP15    [Toc]    [Back]
                This command returns the current HP15 character that has
                been set via the EUC_SET_HP15 command.  This command takes a
                pointer to an integer via which the result is returned.  If
                no previous EUC_SET_HP15 has been issued, then it will
                return HP15_ASCII.

    BSD 4.3 Compatible Terminal I/O Commands
      The ldterm module acts on the following I/O commands, which are
      compatible with the BSD I/O environment:

      TIOCEXCL  Set `exclusive-use' mode.  No further opens are permitted
                until the file has been closed.

      TIOCNXCL  Turn off `exclusive-use' mode.

      TIOCSETD  The ldterm module does nothing but reply to this command.
                In a BSD system, the command is used to set the current line
                discipline type. It does not have much meaning in a STREAMS
                environment, because line discipline modules are changed by
                popping the current module from the stream and pushing a
                different one onto the stream.

      TIOCGETD  In a BSD system, this command is used to get the current
                line discipline type. The command does not have much meaning
                in a STREAMS environment.  The ldterm module replies with a
                value of 2 for binary compatibility, since ldterm supports



 Hewlett-Packard Company            - 7 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




                job control.

      TIOCFLUSH This command flush the input or/and output streams similar
                to that of the TCFLSH command.  The argument is a pointer to
                an int variable. If its value is zero, both the input and
                output streams are flushed by sending the appropriate
                FLUSHR/FLUSHW M_FLUSH messages upstream and downstream.
                Otherwise, the value of the int is treated as the logical OR
                of the FREAD and FWRITE flags defined by <sys/file.h>.  If
                the FREAD flag is set, the input stream is flushed.  If the
                FWRITE flag is set, the output stream is flushed.  Then,
                ldterm acknowledges the message with M_IOCACK.

      TIOCOUTQ  This command takes a pointer to an integer and returns the
                number of characters buffered up in the ldterm's output
                buffer.

      TIOCHPCL  This command sets the POSIX termios HUPCL flag to indicate
                that the terminal line should be disconnected when the last
                file descriptor associated with that line is closed.  The
                ldterm module converts the command into a compatible POSIX
                termios I/O control command by sending an M_IOCTL message
                containing the TCSETS command with current termios settings
                downstream.

      TIOCSTART The command restarts output. If the terminal was stopped,
                the ldterm module sends an M_START message downstream.

      TIOCSTOP  This command stops output. The ldterm module sends an M_STOP
                message downstream.

      TIOCSBRK  This command sets the break condition on a line.  The ldterm
                module sends an M_BREAK message containing a value of 1 as
                data to the driver, then replies with M_IOCACK

      TIOCCBRK  This command clears the break condition on a line.  The
                ldterm module sends an M_BREAK message containing a value of
                0 (zero) as data to the driver, then replies with M_IOCACK.

      TIOCSETP, TIOCSETN
                These commands set the sgttyb information, defined in
                <sys/ttold.h>.  The argument is a pointer to an sgttyb
                structure.  The ldterm module converts the message to a
                POSIX termios M_IOCTL message.  Then, it forwards the POSIX
                termios M_IOCTL message with a corresponding POSIX termios
                command (i.e. TCSETSW, TCSETS).  The original I/O control
                command and M_IOCTL message are stored for use on M_IOCACK.

      TIOCGETP  This  command returns the sgttyb information based on the
                interpretation of the current content of the POSIX termios
                structure maintained in ldterm.  The argument is a pointer



 Hewlett-Packard Company            - 8 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




                to an sgttyb structure via where the information is
                returned.

      TIOCSETC  This command sets the tchars information, defined in
                <sys/strtio.h>.  The argument is a pointer to an tchars
                structure.  The ldterm module converts the message to a
                POSIX termios M_IOCTL message.  Then, it forwards the POSIX
                termios M_IOCTL message with a corresponding POSIX termios
                command (i.e. TCSETS).  The original I/O control command and
                M_IOCTL message are stored for use on M_IOCACK.

      TIOCGETC  This  command returns the tchars information based on the
                interpretation of the current content of the POSIX termios
                structure maintained in ldterm.  The argument is a pointer
                to an tchars structure via where the information is
                returned.

      TIOCSLTC  This command sets the ltchars information defined in
                <sys/bsdtty.h>.  The ldterm module converts the message to a
                POSIX termios M_IOCTL message.  Then, it forwards the POSIX
                termios M_IOCTL message with a corresponding POSIX termios
                command (i.e. TCSETS).  The original I/O control command and
                M_IOCTL message are stored for use on M_IOCACK.

      TIOCGLTC  The ldterm module returns the ltchars information based on
                the interpretation of the current content of the POSIX
                termios structure maintained in ldterm.

      TIOCLBIS, TIOCLBIC, TIOCLSET
                These commands set the BSD 4.3 flags information, defined in
                <sys/strtio.h>.  For TIOCLBIS and TIOCLBIC, the argument is
                a pointer to an int whose value is a mask containing flags
                to be set/clear.  For TIOCLSET, the argument is a pointer to
                an int whose value is a new set of flags to be set.  The
                ldterm module converts the message to a POSIX termios
                M_IOCTL, then forwards the POSIX termios M_IOCTL message
                with a corresponding POSIX termios command (i.e. TCSETS).
                It stores the original I/O control command and M_IOCTL
                message to be used on M_IOCACK.

      TIOCLGET  The ldterm module returns the BSD 4.3 flags information
                based on the interpretation of the current content of the
                POSIX termios structure maintained in ldterm.

      TIOCSTI   This command takes an argument of a pointer to a character
                and pretends that the character was typed on the terminal.
                The user must either have superuser privilege or have read
                permission on the controlling terminal which the ioctl is
                issued against.





 Hewlett-Packard Company            - 9 -   HP-UX 11i Version 2: August 2003






 ldterm(7)                                                         ldterm(7)




      FIONREAD  This command takes an argument of a pointer to an integer
                and returns the number of immediately readable characters.

 AUTHOR    [Toc]    [Back]
      ldterm was developed by HP and OSF.

 SEE ALSO    [Toc]    [Back]
      ioctl(2), streamio(7), termio(7), ptm(7), pts(7), ptem(7).


 Hewlett-Packard Company           - 10 -   HP-UX 11i Version 2: August 2003
[ Back ]
      
      
 Similar pages
Name OS Title
ldterm Tru64 STREAMS line discipline module
termios FreeBSD general terminal line discipline
termios OpenBSD general terminal line discipline
uugetty HP-UX set terminal type, modes, speed and line discipline
uugetty IRIX set terminal type, modes, speed, and line discipline
getty IRIX set terminal type, modes, speed, and line discipline
getty HP-UX set terminal type, modes, speed, and line discipline
getty Tru64 Sets the terminal type, modes, speed, and line discipline
ptem HP-UX STREAMS pty (pesudo-terminal) Emulation module
pckt HP-UX Packet Mode module for STREAMS pty (pseudo-terminal)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service