COHERENT manpages
This page displays the COHERENT manpage for sgtty [General terminal interface].
List of available manpages
Index
sgtty -- Device Driver General terminal interface COHERENT uses two method for controlling terminals: sgtty and termio. To use sgtty, simply include the statement #include <sgtty.h> in your sources. To use termio, include the statement #include <termio.h>. The rest of this article discusses the sgtty method of controlling terminals. When a terminal file is opened, it normally causes the process to wait until a connection is established. In practice, users' programs seldom open these files; they are opened by the program getty and become a user's standard input, output, and error files. The very first terminal file opened by the process group leader of a terminal file not already associated with a process group becomes the controlling terminal for that process group. The controlling terminal plays a special role in handling quit and interrupt signals, as discussed below. The controlling terminal is inherited by a child process during a call to fork. A process can break this association by changing its process group using setpgrp. A terminal associated with one of these files ordinarily operates in full- duplex mode. Characters can be typed at any time, even while output is occurring, and are only lost when the system's input buffers become completely full, which is rare, or when the user has accumulated the maximum allowed number of input characters that have not yet been read by some program. Currently, this limit is 256 characters. When the input limit is reached, the sytems throws away all the saved characters without notice. Normally, terminal input is processed in units of lines. A line is delimited by a newline character (ASCII LF) or an end-of-file character (ASCII EOT). Unless otherwise directed, a program attempting to read will be suspended until an entire line has been typed. Also, no matter how many characters are requested in the read call, at most one line will be returned. It is not, however, necessary to read a whole line at once; any number of characters may be requested in a read, even one, without losing information. During input, the system normally processes erase and kill characters. By default, the backspace character erases the last character typed, except that it will not erase beyond the beginning of the line. By default, the <ctrl-U> kills (deletes) the entire input line, and optionally outputs a newline character. Both these characters operate on a keystroke- by-keystroke basis, independently of any backspacing or tabbing which may have been done. Both the erase and kill characters may be entered literally by preceding them with the escape character (\). In this case, the escape character is not read. You may change the erase and kill characters via command stty. Certain characters have special functions on input. These functions and their default character values are summarized as follows: INTR (<ctrl-C> or ASCII ETX) generates an interrupt signal that is sent to all processes associated with the controlling terminal. Normally, each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location; see the Lexicon entry for signal. QUIT (Control-\ or ASCII ES) generates a quit signal. Its treatment is identical to that of the interrupt signal except that, unless a receiving process has made other arrangements, it will not only be terminated but a core image file (called core) will be created in the current working directory. ERASE (<backspace> or ASCII BS) erases the preceding character. It will not erase beyond the start of a line, as delimited by a newline or EOF character. KILL (<ctrl-U> or ASCII NAK) deletes the entire line, as delimited by a newline or EOF character. EOF (<ctrl-D> or ASCII EOT) generates an end-of-file character from a terminal. When received, all the characters waiting to be read are immediately passed to the program without waiting for a newline, and the EOF is discarded. Thus, if no characters are waiting, which is to say the EOF occurred at the beginning of a line. zero characters will be passed back, which is the standard end-of-file indication. NL (ASCII LF) is the normal line delimiter. It cannot be changed or escaped. STOP (<ctrl-S> or ASCII DC3) can be used to suspend output. It is useful with CRT terminals to prevent output from disappearing before it can be read. While output is suspended, STOP characters are ignored and not read. START (<ctrl-Q> or ASCII DC1) resumes output that has been suspended by a STOP character. While output is not suspended, START characters are ignored and not read. The start/stop characters can be changed via command stty, or via special ioctl() calls described below. The character values for INTR, QUIT, ERASE, EOF, and KILL may be changed to suit individual tastes. The ERASE, KILL, and EOF character may be escaped by a preceding \ character, in which case the system ignores its special meaning. See the Lexicon article on stty for information on how to change these settings dynamically. When using a ``modem control'' serial line, loss of carrier from the data- set (modem) causes a hangup signal to be sent to all processes that have this terminal as the controlling terminal. Unless other arrangements have been made, this signal causes the process to terminate. If the hangup signal is ignored, any subsequent read returns with an end-of-file indication. Thus programs that read a terminal and test for end-of-file can terminate appropriately when hung up on. When one or more characters are written, they are transmitted to the terminal as soon as previously written characters have finished typing. Input characters are echoed by putting them into the output queue as they arrive. If a process produces characters more rapidly than they can be printed, it will be suspended when its output queue exceeds some limit, known as the ``high water mark''. When the queue has ``drained'' down to some threshold, the program resumes. The header file <sgtty.h> declares structures and manifest constants to control the sgtty interface. Of interest to users are the constants that define baud rates for terminal ports; these are as follows. B50 50 baud B75 75 baud B110 110 baud B134 134 baud B150 150 baud B200 200 baud B300 300 baud B600 600 baud B1200 1200 baud B1800 1800 baud B2400 2400 baud B4800 4800 baud B9600 9600 baud B19200 19,200 baud B38400 38,400 baud Terminal ioctl() Functions Header file <sgtty.h> defines the following data structures used by the various device drivers to convey terminal specific information. These structures are used in conjunction with special terminal or device driver symbolic constants as part of ioctl() requests. The sgttyb structure contains information related to line discipline, such as serial line speed, if appropriate, the ``erase'' and ``kill'' characters, and a series of flags which set the mode of the line. /* * Structure for TIOCSETP/TIOCGETP */ struct sgttyb { char sg_ispeed;/* Input speed */ char sg_ospeed;/* Output speed */ char sg_erase; /* Character erase */ char sg_kill; /* Line kill character */ int sg_flags; /* Flags */ }; The following symbolic constants are used to access bit positions of member sg_flags in data structure sgttyb: CBREAK Each input character causes wakeup (i.e., forces a return from a read() system call). CRMOD Map the carriage return characters '\r' to the newline character '\n'. CRT Use CRT-style character erase. ECHO Echo input characters. EVENP Select even parity. If used in conjunction with ODDP, allow either parity. LCASE Lowercase mapping on input. ODDP Select odd parity. If used in conjunction with EVENP, allow either parity. RAW Raw mode. Same as RAWIN plus RAWOUT. RAWIN Input is treated as 8-bit characters and not interpreted. RAWOUT Output is treated as 8-bit characters and not interpreted. TANDEM Use X-ON/X-OFF flow control protocol to remote device. XTABS Expand tabs to spaces. Data structure tchars specifies additional special terminal characters such as the ``interrupt'' and ``quit'' characters, the ``start'' and ``stop'' characters used for flow control, and the ``end-of-file'' character. /* * Structure for TIOCSETC/TIOCGETC */ struct tchars { char t_intrc; /* Interrupt */ char t_quitc; /* Quit */ char t_startc; /* Start output */ char t_stopc; /* Stop output */ char t_eofc; /* End of file */ char t_brkc; /* Input delimiter */ }; The following symbolic constants are used to access various device functions via ioctl() calls, as defined in header file <sgtty.h>. Note that not all functions are appropriate for all classes of devices. TIOCCBRK Clear a BREAK condition on a serial line (i.e., ``mark'' the line). This request cancels a previously issued TIOCSBRK request. TIOCCDTR Clear modem control signal Data Terminal Ready (DTR) on a serial line. TIOCCHPCL Do not force a hangup on ``last close'' on a modem line. The normal mode of operation for serial lines is to drop modem signal Data Terminal Ready (DTR) when the last close() operation is performed, thus requesting the attached modem to drop the connection. TIOCCRTS Clear the Request To Send (RTS) signal on a serial line. Modem control signal RTS is often used for hardware flow control. TIOCEXCL Set device access as exclusive use. This request requires the process to have root privileges. TIOCFLUSH Flush the input queue, discarding any pending input characters, and wait for the output queue to ``drain''. TIOCGETC Get current values of the special terminal characters, as defined by data structure tchars. TIOCGETF Get current console keyboard function key bindings. This request is specific to the nkb console keyboard device driver. See Lexicon article nkb for further details. TIOCGETKBT Get current console keyboard key mapping table. This request is specific to the nkb console keyboard device driver. See Lexicon article nkb for further details. TIOCGETP Get current terminal line settings, as defined by data structure sgttyb. TIOCGETTF Get current value of the terminal flags, as defined by field t_flags in the TTY structure. TIOCHPCL Set hangup on ``last close''. See TIOCCHPCL for further details. TIOCRMSR Get the current value of the Modem Status Register (MSR) for the specified serial line. This request is device driver specific and is currently supported only in the al device driver. Symbolic constants MSRCTS, MSRDSR, MSRRI, and MSRRLSD correspond to the Clear To Send, Data Set Ready, Ring Indicator and Receive Line Status Detect (i.e. Carrier Detect) signals, respectively, in the MSR. TIOCNXCL Set this device or port as non-exclusive use. See TIOCEXCL for further details. TIOCQUERY Query the number of characters currently waiting in the input queue. TIOCSBRK Assert BREAK (i.e., ``space the line'') on the given serial port. This is often used during login to signal a remote system to ``hunt'' to the next baud rate in a sequence. See TIOCCBRK for further details. TIOCSDTR Assert modem control signal Data Terminal Ready (DTR) on a serial line. TIOCSETC Wait for output to ``drain'', then set the terminal control characters for this device, as specified by data structure tchars. TIOCSETF Set console keyboard function key mapping. This request is specific to the nkb console keyboard device driver. See Lexicon article nkb for further details. TIOCSETKBT Set console keyboard key mapping table. This request is specific to the nkb console keyboard device driver. See Lexicon article nkb for further details. TIOCSETN Set terminal line settings, as defined by data structure sgttyb. Do not flush the input queue prior to using the new settings. TIOCSETP Same as request TIOCSETN, but also flush the input queue. TIOCSRTS Assert the Request To Send (RTS) signal on a serial line. Modem control signal RTS is often used for hardware flow control. Examples The following code fragment gets the current terminal settings and turns off echo. #include <sgtty.h> static struct sgttyb new, orig; . . . /* * Get the existing terminal parameters for the terminal * device associated with file descriptor 0 (stdin), * turn off echo, turn on CBREAK (break on every input character) * and set the new parameters. */ ioctl(0, TIOCGETP, &orig); new = orig; new.sg_flags &= ~ECHO; /* Turn off echo */ new.sg_flags |= CBREAK; /* Turn on CBREAK mode */ ioctl(0, TIOCSETN, &new); The following line uses the previously saved terminal mode to return the terminal mode to its prior state: ioctl(0, TIOCSETN, &orig); See Also device drivers, gtty(), ioctl(), sgtty.h, stty, stty(), terminal, termio