share/man/man4/tty.4

   1 .\" Copyright (c) 1991, 1992, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)tty.4       8.3 (Berkeley) 4/19/94
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd Jun 27, 2007
  36 .Dt TTY 4
  37 .Os
  38 .Sh NAME
  39 .Nm tty
  40 .Nd general terminal interface
  41 .Sh SYNOPSIS
  42 .In sys/ioctl.h
  43 .Sh DESCRIPTION
  44 This section describes the interface to the terminal drivers
  45 in the system.
  46 .Ss Terminal Special Files
  47 Each hardware terminal port on the system usually has a terminal special device
  48 file associated with it in the directory ``/dev/'' (for
  49 example, ``/dev/tty03'').
  50 When a user logs into
  51 the system on one of these hardware terminal ports, the system has already
  52 opened the associated device and prepared the line for normal interactive
  53 use (see
  54 .Xr getty 8 . )
  55 There is also a special case of a terminal file that connects not to
  56 a hardware terminal port, but to another program on the other side.
  57 These special terminal devices are called
  58 .Em ptys
  59 and provide the mechanism necessary to give users the same interface to the
  60 system when logging in over a network (using
  61 .Xr rlogin 1 ,
  62 or
  63 .Xr telnet 1
  64 for example).
  65 Even in these cases the details of how the terminal
  66 file was opened and set up is already handled by special software
  67 in the system.
  68 Thus, users do not normally need to worry about the details of
  69 how these lines are opened or used.
  70 Also, these lines are often used
  71 for dialing out of a system (through an out-calling modem), but again
  72 the system provides programs that hide the details of accessing
  73 these terminal special files (see
  74 .Xr tip 1 ) .
  75 .Pp
  76 When an interactive user logs in, the system prepares the line to
  77 behave in a certain way (called a
  78 .Em "line discipline" ) ,
  79 the particular details of which is described in
  80 .Xr stty 1
  81 at the command level, and in
  82 .Xr termios 4
  83 at the programming level.
  84 A user may be concerned with changing
  85 settings associated with his particular login terminal and should refer
  86 to the preceding man pages for the common cases.
  87 The remainder of this man page is concerned
  88 with describing details of using and controlling terminal devices
  89 at a low level, such as that possibly required by a program wishing
  90 to provide features similar to those provided by the system.
  91 .Ss Line disciplines
  92 A terminal file is used like any other file in the system in that
  93 it can be opened, read, and written to using standard system
  94 calls.
  95 For each existing terminal file, there is a software processing module
  96 called a
  97 .Em "line discipline"
  98 is associated with it.
  99 The
 100 .Em "line discipline"
 101 essentially glues the low level device driver code with the high
 102 level generic interface routines (such as
 103 .Xr read 2
 104 and
 105 .Xr write 2 ) ,
 106 and is responsible for implementing the semantics associated
 107 with the device.
 108 When a terminal file is first opened by a program, the default
 109 .Em "line discipline"
 110 called the
 111 .Dv termios
 112 line discipline is associated with the file.
 113 This is the primary
 114 line discipline that is used in most cases and provides the semantics
 115 that users normally associate with a terminal.
 116 When the
 117 .Dv termios
 118 line discipline is in effect, the terminal file behaves and is
 119 operated according to the rules described in
 120 .Xr termios 4 .
 121 Please refer to that man page for a full description of the terminal
 122 semantics.
 123 The operations described here
 124 generally represent features common
 125 across all
 126 .Em "line disciplines" ,
 127 however some of these calls may not
 128 make sense in conjunction with a line discipline other than
 129 .Dv termios ,
 130 and some may not be supported by the underlying
 131 hardware (or lack thereof, as in the case of ptys).
 132 .Ss Terminal File Operations
 133 All of the following operations are invoked using the
 134 .Xr ioctl 2
 135 system call.
 136 Refer to that man page for a description of the
 137 .Em request
 138 and
 139 .Em argp
 140 parameters.
 141 In addition to the ioctl
 142 .Em requests
 143 defined here, the specific line discipline
 144 in effect will define other
 145 .Em requests
 146 specific to it (actually
 147 .Xr termios 4
 148 defines them as function calls, not ioctl
 149 .Em requests . )
 150 The following section lists the available ioctl requests.
 151 The name of the request, a description of its purpose, and the typed
 152 .Em argp
 153 parameter (if any)
 154 are listed.
 155 For example, the first entry says
 156 .Pp
 157 .D1 Em "TIOCSETD int *ldisc"
 158 .Pp
 159 and would be called on the terminal associated with
 160 file descriptor zero by the following code fragment:
 161 .Bd -literal
 162         int ldisc;
 163
 164         ldisc = TTYDISC;
 165         ioctl(0, TIOCSETD, &ldisc);
 166 .Ed
 167 .Ss Terminal File Request Descriptions
 168 .Bl -tag -width TIOCGWINSZ
 169 .It Dv TIOCSETD Fa int *ldisc
 170 Change to the new line discipline pointed to by
 171 .Fa ldisc .
 172 The available line disciplines are listed in
 173 .In sys/ttycom.h
 174 and currently are:
 175 .Pp
 176 .Bl -tag -width NETGRAPHDISC -compact
 177 .It TTYDISC
 178 Termios interactive line discipline.
 179 .It TABLDISC
 180 Tablet line discipline.
 181 .It SLIPDISC
 182 Serial IP line discipline.
 183 .It PPPDISC
 184 PPP line discipline.
 185 .It NETGRAPHDISC
 186 Netgraph
 187 .Xr ng_tty 4
 188 line discipline.
 189 .El
 190 .Pp
 191 .It Dv TIOCGETD Fa int *ldisc
 192 Return the current line discipline in the integer pointed to by
 193 .Fa ldisc .
 194 .It Dv TIOCSBRK Fa void
 195 Set the terminal hardware into BREAK condition.
 196 .It Dv TIOCCBRK Fa void
 197 Clear the terminal hardware BREAK condition.
 198 .It Dv TIOCSDTR Fa void
 199 Assert data terminal ready (DTR).
 200 .It Dv TIOCCDTR Fa void
 201 Clear data terminal ready (DTR).
 202 .It Dv TIOCGPGRP Fa int *tpgrp
 203 Return the current process group with which the terminal is associated
 204 in the integer pointed to by
 205 .Fa tpgrp .
 206 This is the underlying call that implements the
 207 .Xr termios 4
 208 .Fn tcgetattr
 209 call.
 210 .It Dv TIOCSPGRP Fa int *tpgrp
 211 Associate the terminal with the process group (as an integer) pointed to by
 212 .Fa tpgrp .
 213 This is the underlying call that implements the
 214 .Xr termios 4
 215 .Fn tcsetattr
 216 call.
 217 .It Dv TIOCGETA Fa struct termios *term
 218 Place the current value of the termios state associated with the
 219 device in the termios structure pointed to by
 220 .Fa term .
 221 This is the underlying call that implements the
 222 .Xr termios 4
 223 .Fn tcgetattr
 224 call.
 225 .It Dv TIOCSETA Fa struct termios *term
 226 Set the termios state associated with the device immediately.
 227 This is the underlying call that implements the
 228 .Xr termios 4
 229 .Fn tcsetattr
 230 call with the
 231 .Dv TCSANOW
 232 option.
 233 .It Dv TIOCSETAW Fa struct termios *term
 234 First wait for any output to complete, then set the termios state
 235 associated with the device.
 236 This is the underlying call that implements the
 237 .Xr termios 4
 238 .Fn tcsetattr
 239 call with the
 240 .Dv TCSADRAIN
 241 option.
 242 .It Dv TIOCSETAF Fa struct termios *term
 243 First wait for any output to complete, clear any pending input,
 244 then set the termios state associated with the device.
 245 This is the underlying call that implements the
 246 .Xr termios 4
 247 .Fn tcsetattr
 248 call with the
 249 .Dv TCSAFLUSH
 250 option.
 251 .It Dv TIOCOUTQ Fa int *num
 252 Place the current number of characters in the output queue in the
 253 integer pointed to by
 254 .Fa num .
 255 .It Dv TIOCSTI Fa char *cp
 256 Simulate typed input.
 257 Pretend as if the terminal received the character pointed to by
 258 .Fa cp .
 259 .It Dv TIOCNOTTY Fa void
 260 This call is obsolete but left for compatibility.
 261 In the past, when a process that did not have a controlling terminal (see
 262 .Em The Controlling Terminal
 263 in
 264 .Xr termios 4 )
 265 first opened a terminal device, it acquired that terminal as its
 266 controlling terminal.
 267 For some programs this was a hazard as they
 268 did not want a controlling terminal in the first place, and this
 269 provided a mechanism to disassociate the controlling terminal from
 270 the calling process.
 271 It
 272 .Em must
 273 be called by opening the file
 274 .Pa /dev/tty
 275 and calling
 276 .Dv TIOCNOTTY
 277 on that file descriptor.
 278 .Pp
 279 The current system does not allocate a controlling terminal to
 280 a process on an
 281 .Fn open
 282 call: there is a specific ioctl called
 283 .Dv TIOCSCTTY
 284 to make a terminal the controlling
 285 terminal.
 286 In addition, a program can
 287 .Fn fork
 288 and call the
 289 .Fn setsid
 290 system call which will place the process into its own session - which
 291 has the effect of disassociating it from the controlling terminal.
 292 This is the new and preferred method for programs to lose their controlling
 293 terminal.
 294 .It Dv TIOCSTOP Fa void
 295 Stop output on the terminal (like typing ^S at the keyboard).
 296 .It Dv TIOCSTART Fa void
 297 Start output on the terminal (like typing ^Q at the keyboard).
 298 .It Dv TIOCSCTTY Fa void
 299 Make the terminal the controlling terminal for the process (the process
 300 must not currently have a controlling terminal).
 301 .It Dv TIOCDRAIN Fa void
 302 Wait until all output is drained.
 303 .It Dv TIOCEXCL Fa void
 304 Set exclusive use on the terminal.
 305 No further opens are permitted except by root.
 306 Of course, this means that programs that are run by
 307 root (or setuid) will not obey the exclusive setting - which limits
 308 the usefulness of this feature.
 309 .It Dv TIOCNXCL Fa void
 310 Clear exclusive use of the terminal.
 311 Further opens are permitted.
 312 .It Dv TIOCFLUSH Fa int *what
 313 If the value of the int pointed to by
 314 .Fa what
 315 contains the
 316 .Dv FREAD
 317 bit as defined in
 318 .In sys/file.h ,
 319 then all characters in the input queue are cleared.
 320 If it contains the
 321 .Dv FWRITE
 322 bit, then all characters in the output queue are cleared.
 323 If the value of the integer is zero, then it behaves as if both the
 324 .Dv FREAD
 325 and
 326 .Dv FWRITE
 327 bits were set (i.e., clears both queues).
 328 .It Dv TIOCGWINSZ Fa struct winsize *ws
 329 Put the window size information associated with the terminal in the
 330 .Va winsize
 331 structure pointed to by
 332 .Fa ws .
 333 The window size structure contains the number of rows and columns (and pixels
 334 if appropriate) of the devices attached to the terminal.
 335 It is set by user software
 336 and is the means by which most full\&-screen oriented programs determine the
 337 screen size.
 338 The
 339 .Va winsize
 340 structure is defined in
 341 .In sys/ioctl.h .
 342 .It Dv TIOCSWINSZ Fa struct winsize *ws
 343 Set the window size associated with the terminal to be the value in
 344 the
 345 .Va winsize
 346 structure pointed to by
 347 .Fa ws
 348 (see above).
 349 .It Dv TIOCCONS Fa int *on
 350 If
 351 .Fa on
 352 points to a non-zero integer, redirect kernel console output (kernel printf's)
 353 to this terminal.
 354 If
 355 .Fa on
 356 points to a zero integer, redirect kernel console output back to the normal
 357 console.
 358 This is usually used on workstations to redirect kernel messages
 359 to a particular window.
 360 .It Dv TIOCMSET Fa int *state
 361 The integer pointed to by
 362 .Fa state
 363 contains bits that correspond to modem state.
 364 Following is a list of defined variables and the modem state they represent:
 365 .Pp
 366 .Bl -tag -width TIOCMXCTS -compact
 367 .It TIOCM_LE
 368 Line Enable.
 369 .It TIOCM_DTR
 370 Data Terminal Ready.
 371 .It TIOCM_RTS
 372 Request To Send.
 373 .It TIOCM_ST
 374 Secondary Transmit.
 375 .It TIOCM_SR
 376 Secondary Receive.
 377 .It TIOCM_CTS
 378 Clear To Send.
 379 .It TIOCM_CAR
 380 Carrier Detect.
 381 .It TIOCM_CD
 382 Carrier Detect (synonym).
 383 .It TIOCM_RNG
 384 Ring Indication.
 385 .It TIOCM_RI
 386 Ring Indication (synonym).
 387 .It TIOCM_DSR
 388 Data Set Ready.
 389 .El
 390 .Pp
 391 This call sets the terminal modem state to that represented by
 392 .Fa state .
 393 Not all terminals may support this.
 394 .It Dv TIOCMGET Fa int *state
 395 Return the current state of the terminal modem lines as represented
 396 above in the integer pointed to by
 397 .Fa state .
 398 .It Dv TIOCMBIS Fa int *state
 399 The bits in the integer pointed to by
 400 .Fa state
 401 represent modem state as described above, however the state is OR-ed
 402 in with the current state.
 403 .It Dv TIOCMBIC Fa int *state
 404 The bits in the integer pointed to by
 405 .Fa state
 406 represent modem state as described above, however each bit which is on
 407 in
 408 .Fa state
 409 is cleared in the terminal.
 410 .El
 411 .Sh IMPLEMENTATION NOTES
 412 The total number of input and output bytes
 413 through all terminal devices
 414 are available via the
 415 .Va kern.tk_nin
 416 and
 417 .Va kern.tk_nout
 418 read-only
 419 .Xr sysctl 8
 420 variables.
 421 .Sh SEE ALSO
 422 .Xr stty 1 ,
 423 .Xr ioctl 2 ,
 424 .Xr ng_tty 4 ,
 425 .Xr pty 4 ,
 426 .Xr termios 4 ,
 427 .Xr getty 8