unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 ldterm(7)							   ldterm(7)




 NAME
      ldterm - standard STREAMS terminal line discipline module

 SYNOPSIS
      #include <&lt&lt&lt;sys/stream.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/stropts.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/termios.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/bsdtty.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/ttold.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/strtio.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/eucioctl.h>&gt&gt&gt;

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

 DESCRIPTION
      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
      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 Release 11i: November 2000






 ldterm(7)							   ldterm(7)




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

    Read-side Behavior
      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 higher-
		order 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 Release 11i: November 2000






 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 <&lt&lt&lt;sys/stream.h>&gt&gt&gt;).  The ioc_cmd member of this
		structure contains a command, just as it does in an M_IOCTL



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 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
		     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
		     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
      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 Release 11i: November 2000






 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
      termio(7) man page. Note: the FIO[xyz] ioctls documented on termio(7)
      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 Release 11i: November 2000






 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
		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
		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 Release 11i: November 2000






 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
		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
		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 Release 11i: November 2000






 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 <&lt&lt&lt;sys/file.h>&gt&gt&gt;.	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
		<&lt&lt&lt;sys/ttold.h>&gt&gt&gt;.	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 Release 11i: November 2000






 ldterm(7)							   ldterm(7)




		to an sgttyb structure via where the information is
		returned.

      TIOCSETC	This command sets the tchars information, defined in
		<&lt&lt&lt;sys/strtio.h>&gt&gt&gt;.	 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
		<&lt&lt&lt;sys/bsdtty.h>&gt&gt&gt;.	 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
		<&lt&lt&lt;sys/strtio.h>&gt&gt&gt;.	 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 Release 11i: November 2000






 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
      ldterm was developed by HP and OSF.

 SEE ALSO
      ioctl(2), streamio(7), termio(7), ptm(7), pts(7), ptem(7).














































 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000