initial import of NetBSD tree

1 files changed, 396 insertions, 0 deletions

diff --git a/share/man/man4/tty.4 b/share/man/man4/tty.4
new file mode 100644
index 00000000000..fa2fab6cbe2
--- /dev/null
+++ b/share/man/man4/tty.4
@@ -0,0 +1,396 @@
+.\"	$NetBSD: tty.4,v 1.2 1994/11/30 16:22:40 jtc Exp $
+.\"
+.\" Copyright (c) 1991, 1992, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)tty.4	8.3 (Berkeley) 4/19/94
+.\"
+.Dd August 14, 1992
+.Dt TTY 4
+.Os BSD 4
+.Sh NAME
+.Nm tty
+.Nd general terminal interface
+.Sh SYNOPSIS
+.Fd #include <sys/ioctl.h>
+.Sh DESCRIPTION
+This section describes the interface to the terminal drivers
+in the system.
+.Ss Terminal Special Files
+Each hardware terminal port on the system usually has a terminal special device
+file associated with it in the directory ``/dev/'' (for
+example, ``/dev/tty03'').
+When a user logs into
+the system on one of these hardware terminal ports, the system has already
+opened the associated device and prepared the line for normal interactive
+use (see
+.Xr getty 8 .)
+There is also a special case of a terminal file that connects not to
+a hardware terminal port, but to another program on the other side.
+These special terminal devices are called
+.Em ptys
+and provide the mechanism necessary to give users the same interface to the
+system when logging in over a network (using
+.Xr rlogin 1 ,
+or
+.Xr telnet 1
+for example.)  Even in these cases the details of how the terminal
+file was opened and set up is already handled by special software
+in the system.
+Thus, users do not normally need to worry about the details of
+how these lines are opened or used.  Also, these lines are often used
+for dialing out of a system (through an out-calling modem), but again
+the system provides programs that hide the details of accessing
+these terminal special files (see
+.Xr tip 2 .)
+.Pp
+When an interactive user logs in, the system prepares the line to
+behave in a certain way (called a
+.Em "line discipline" ) ,
+the particular details of which is described in
+.Xr stty 1
+at the command level, and in
+.Xr termios 4
+at the programming level.  A user may be concerned with changing
+settings associated with his particular login terminal and should refer
+to the preceding man pages for the common cases.  The remainder of
+this man page is concerned
+with describing details of using and controlling terminal devices
+at a low level, such as that possibly required by a program wishing
+to provide features similar to those provided by the system.
+.Ss Line disciplines
+A terminal file is used like any other file in the system in that
+it can be opened, read, and written to using standard system
+calls.  For each existing terminal file, there is a software processing module
+called a
+.Em "line discipline"
+is associated with it.  The
+.Em "line discipline"
+essentially glues the low level device driver code with the high
+level generic interface routines (such as
+.Xr read 2
+and
+.Xr write 2 ),
+and is responsible for implementing the semantics associated
+with the device.  When a terminal file is first opened by a program,
+the default
+.Em "line discipline"
+called the
+.Dv termios
+line discipline is associated with the file.  This is the primary
+line discipline that is used in most cases and provides the semantics
+that users normally associate with a terminal.  When the
+.Dv termios
+line discipline is in effect, the terminal file behaves and is
+operated according to the rules described in
+.Xr termios 4 .
+Please refer to that man page for a full description of the terminal
+semantics.
+The operations described here
+generally represent features common
+across all
+.Em "line disciplines" ,
+however some of these calls may not
+make sense in conjunction with a line discipline other than
+.Dv termios ,
+and some may not be supported by the underlying
+hardware (or lack thereof, as in the case of ptys).
+.Ss Terminal File Operations
+All of the following operations are invoked using the
+.Xr ioctl 2
+system call.  Refer to that man page for a description of
+the
+.Em request
+and
+.Em argp
+parameters.
+In addition to the ioctl
+.Em requests
+defined here, the specific line discipline
+in effect will define other
+.Em requests
+specific to it (actually
+.Xr termios 4
+defines them as function calls, not ioctl
+.Em requests . )
+The following section lists the available ioctl requests.  The
+name of the request, a description of its purpose, and the typed
+.Em argp
+parameter (if any)
+are listed.  For example, the first entry says
+.Pp
+.D1 Em "TIOCSETD int *ldisc"
+.Pp
+and would be called on the terminal associated with
+file descriptor zero by the following code fragment:
+.Bd -literal
+	int ldisc;
+
+	ldisc = TTYDISC;
+	ioctl(0, TIOCSETD, &ldisc);
+.Ed
+.Ss Terminal File Request Descriptions
+.Bl -tag -width TIOCGWINSZ
+.It Dv TIOCSETD Fa int *ldisc
+Change to the new line discipline pointed to by
+.Fa ldisc .
+The available line disciplines are listed in
+.Pa Aq sys/termios.h
+and currently are:
+.Pp
+.Bl -tag -width TIOCGWINSZ -compact
+.It TTYDISC
+Termios interactive line discipline.
+.It TABLDISC
+Tablet line discipline.
+.It SLIPDISC
+Serial IP line discipline.
+.El
+.Pp
+.It Dv TIOCGETD Fa int *ldisc
+Return the current line discipline in the integer pointed to by
+.Fa ldisc .
+.It Dv TIOCSBRK Fa void
+Set the terminal hardware into BREAK condition.
+.It Dv TIOCCBRK Fa void
+Clear the terminal hardware BREAK condition.
+.It Dv TIOCSDTR Fa void
+Assert data terminal ready (DTR).
+.It Dv TIOCCDTR Fa void
+Clear data terminal ready (DTR).
+.It Dv TIOCGPGRP Fa int *tpgrp
+Return the current process group the terminal is associated
+with in the integer pointed to by
+.Fa tpgrp .
+This is the underlying call that implements the
+.Xr termios 4
+.Fn tcgetattr
+call.
+.It Dv TIOCSPGRP Fa int *tpgrp
+Associate the terminal with the process group (as an integer) pointed to by
+.Fa tpgrp .
+This is the underlying call that implements the
+.Xr termios 4
+.Fn tcsetattr
+call.
+.It Dv TIOCGETA Fa struct termios *term
+Place the current value of the termios state associated with the
+device in the termios structure pointed to by
+.Fa term .
+This is the underlying call that implements the
+.Xr termios 4
+.Fn tcgetattr
+call.
+.It Dv TIOCSETA Fa struct termios *term
+Set the termios state associated with the device immediately.
+This is the underlying call that implements the
+.Xr termios 4
+.Fn tcsetattr
+call with the
+.Dv TCSANOW
+option.
+.It Dv TIOCSETAW Fa struct termios *term
+First wait for any output to complete, then set the termios state
+associated with the device.
+This is the underlying call that implements the
+.Xr termios 4
+.Fn tcsetattr
+call with the
+.Dv TCSADRAIN
+option.
+.It Dv TIOCSETAF Fa struct termios *term
+First wait for any output to complete, clear any pending input,
+then set the termios state associated with the device.
+This is the underlying call that implements the
+.Xr termios 4
+.Fn tcsetattr
+call with the
+.Dv TCSAFLUSH
+option.
+.It Dv TIOCOUTQ Fa int *num
+Place the current number of characters in the output queue in the
+integer pointed to by
+.Fa num .
+.It Dv TIOCSTI Fa char *cp
+Simulate typed input.  Pretend as if the terminal received the
+character pointed to by
+.Fa cp .
+.It Dv TIOCNOTTY Fa void
+This call is obsolete but left for compatibility.  In the past, when
+a process that didn't have a controlling terminal (see
+.Em The Controlling Terminal
+in
+.Xr termios 4 )
+first opened a terminal device, it acquired that terminal as its
+controlling terminal.  For some programs this was a hazard as they
+didn't want a controlling terminal in the first place, and this
+provided a mechanism to disassociate the controlling terminal from
+the calling process.  It
+.Em must
+be called by opening the file
+.Pa /dev/tty
+and calling
+.Dv TIOCNOTTY
+on that file descriptor.
+.Pp
+The current system does not allocate a controlling terminal to
+a process on an
+.Fn open
+call: there is a specific ioctl called
+.Dv TIOSCTTY
+to make a terminal the controlling
+terminal.
+In addition, a program can
+.Fn fork
+and call the
+.Fn setsid
+system call which will place the process into its own session - which
+has the effect of disassociating it from the controlling terminal.  This
+is the new and preferred method for programs to lose their controlling
+terminal.
+.It Dv TIOCSTOP Fa void
+Stop output on the terminal (like typing ^S at the keyboard).
+.It Dv TIOCSTART Fa void
+Start output on the terminal (like typing ^Q at the keyboard).
+.It Dv TIOCSCTTY Fa void
+Make the terminal the controlling terminal for the process (the process
+must not currently have a controlling terminal).
+.It Dv TIOCDRAIN Fa void
+Wait until all output is drained.
+.It Dv TIOCEXCL Fa void
+Set exclusive use on the terminal.  No further opens are permitted
+except by root.  Of course, this means that programs that are run by
+root (or setuid) will not obey the exclusive setting - which limits
+the usefulness of this feature.
+.It Dv TIOCNXCL Fa void
+Clear exclusive use of the terminal.  Further opens are permitted.
+.It Dv TIOCFLUSH Fa int *what
+If the value of the int pointed to by
+.Fa what
+contains the
+.Dv FREAD
+bit as defined in
+.Pa Aq sys/file.h ,
+then all characters in the input queue are cleared.  If it contains
+the
+.Dv FWRITE
+bit, then all characters in the output queue are cleared.  If the
+value of the integer is zero, then it behaves as if both the
+.Dv FREAD
+and
+.Dv FWRITE
+bits were set (i.e. clears both queues).
+.It Dv TIOCGWINSZ Fa struct winsize *ws
+Put the window size information associated with the terminal in the
+.Va winsize
+structure pointed to by
+.Fa ws .
+The window size structure contains the number of rows and columns (and pixels
+if appropriate) of the devices attached to the terminal.  It is set by user software
+and is the means by which most full\&-screen oriented programs determine the
+screen size.  The
+.Va winsize
+structure is defined in
+.Pa Aq sys/ioctl.h .
+.It Dv TIOCSWINSZ Fa struct winsize *ws
+Set the window size associated with the terminal to be the value in
+the
+.Va winsize
+structure pointed to by
+.Fa ws
+(see above).
+.It Dv TIOCCONS Fa int *on
+If
+.Fa on
+points to a non-zero integer, redirect kernel console output (kernel printf's)
+to this terminal.
+If
+.Fa on
+points to a zero integer, redirect kernel console output back to the normal
+console.  This is usually used on workstations to redirect kernel messages
+to a particular window.
+.It Dv TIOCMSET Fa int *state
+The integer pointed to by
+.Fa state
+contains bits that correspond to modem state.  Following is a list
+of defined variables and the modem state they represent:
+.Pp
+.Bl -tag -width TIOCMXCTS -compact
+.It TIOCM_LE
+Line Enable.
+.It TIOCM_DTR
+Data Terminal Ready.
+.It TIOCM_RTS
+Request To Send.
+.It TIOCM_ST
+Secondary Transmit.
+.It TIOCM_SR
+Secondary Receive.
+.It TIOCM_CTS
+Clear To Send.
+.It TIOCM_CAR
+Carrier Detect.
+.It TIOCM_CD
+Carier Detect (synonym).
+.It TIOCM_RNG
+Ring Indication.
+.It TIOCM_RI
+Ring Indication (synonym).
+.It TIOCM_DSR
+Data Set Ready.
+.El
+.Pp
+This call sets the terminal modem state to that represented by
+.Fa state .
+Not all terminals may support this.
+.It Dv TIOCMGET Fa int *state
+Return the current state of the terminal modem lines as represented
+above in the integer pointed to by
+.Fa state .
+.It Dv TIOCMBIS Fa int *state
+The bits in the integer pointed to by
+.Fa state
+represent modem state as described above, however the state is OR-ed
+in with the current state.
+.It Dv TIOCMBIC Fa int *state
+The bits in the integer pointed to by
+.Fa state
+represent modem state as described above, however each bit which is on
+in
+.Fa state
+is cleared in the terminal.
+.El
+.Sh SEE ALSO
+.Xr getty 8 ,
+.Xr ioctl 2 ,
+.Xr pty 4 ,
+.Xr stty 1 ,
+.Xr termios 4