.\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
.\" and Andries Brouwer <aeb@cwi.nl>.
-.\" Distributed under GPL.
.\"
-.TH TTY_IOCTL 4 2008-10-29 "Linux" "Linux Programmer's Manual"
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
+.\" Distributed under GPL
+.\" %%%LICENSE_END
+.\"
+.TH TTY_IOCTL 4 2013-11-12 "Linux" "Linux Programmer's Manual"
.SH NAME
tty_ioctl \- ioctls for terminals and serial lines
.SH SYNOPSIS
The
.BR ioctl (2)
call for terminals and serial ports accepts many possible command arguments.
-Most require a third argument, of varying type, here called \fIargp\fP
-or \fIarg\fP.
+Most require a third argument, of varying type, here called
+.I argp
+or
+.IR arg .
.LP
Use of
.I ioctl
Use the POSIX interface described in
.BR termios (3)
whenever possible.
-.SS "Get and Set Terminal Attributes"
+.SS Get and set terminal attributes
.TP
.BI "TCGETS struct termios *" argp
Equivalent to
.BR TCSETSW ,
.BR TCSETSF ,
except that they take a
-.I "struct termio *"
+.I "struct termio\ *"
instead of a
-.IR "struct termios *" .
-.TP
+.IR "struct termios\ *" .
+.IP
.BI "TCGETA struct termio *" argp
-.TP
+.IP
.BI "TCSETA const struct termio *" argp
-.TP
+.IP
.BI "TCSETAW const struct termio *" argp
-.TP
+.IP
.BI "TCSETAF const struct termio *" argp
-.SS "Locking the termios structure"
+.SS Locking the termios structure
The
.I termios
structure of a terminal can be locked.
Sets the locking status of the
.I termios
structure of the terminal.
-Only root (more precisely: a process with the
+Only a process with the
.BR CAP_SYS_ADMIN
-capability) can do this.
-.SS "Get and Set Window Size"
+capability can do this.
+.SS Get and set window size
Window sizes are kept in the kernel, but not used by the kernel
(except in the case of virtual consoles, where the kernel will
update the window size when the size of the virtual console changes,
.B SIGWINCH
signal is sent to the
foreground process group.
-.SS "Sending a Break"
+.SS Sending a break
.TP
.BI "TCSBRK int " arg
Equivalent to
.TP
.B "TIOCCBRK void"
Turn break off, that is, stop sending zero bits.
-.SS "Software flow control"
+.SS Software flow control
.TP
.BI "TCXONC int " arg
Equivalent to
.BR TCOON ,
.BR TCIOFF ,
.BR TCION .
-.SS "Buffer count and flushing"
+.SS Buffer count and flushing
.TP
.BI "FIONREAD int *" argp
Get the number of bytes in the input buffer.
.BR TCIFLUSH ,
.BR TCOFLUSH ,
.BR TCIOFLUSH .
-.SS "Faking input"
+.SS Faking input
.TP
.BI "TIOCSTI const char *" argp
Insert the given byte in the input queue.
-.SS "Redirecting console output"
+.SS Redirecting console output
.TP
.B "TIOCCONS void"
Redirect output that would have gone to
If that was a pseudoterminal master, send it to the slave.
In Linux before version 2.6.10,
anybody can do this as long as the output was not redirected yet;
-since version 2.6.10, only root (a process with the
+since version 2.6.10, only a process with the
.BR CAP_SYS_ADMIN
-capability) may do this.
+capability may do this.
If output was redirected already
.B EBUSY
is returned,
.I /dev/console
or
.IR /dev/tty0 .
-.SS "Controlling terminal"
+.SS Controlling terminal
.TP
.BI "TIOCSCTTY int " arg
Make the given terminal the controlling terminal of the calling process.
The calling process must be a session leader and not have a
controlling terminal already.
+For this case,
+.I arg
+should be specified as zero.
+
If this terminal is already the controlling terminal
-of a different session group then the ioctl fails with
+of a different session group, then the ioctl fails with
.BR EPERM ,
-unless the caller is root (more precisely: has the
+unless the caller has the
.BR CAP_SYS_ADMIN
-capability) and
+capability and
.I arg
equals 1, in which case the terminal is stolen, and all processes that had
it as controlling terminal lose it.
.TP
-.B TIOCNOTTY void
+.B "TIOCNOTTY void"
If the given terminal was the controlling terminal of the calling process,
give up this controlling terminal.
If the process was session leader,
.B SIGCONT
to the foreground process group
and all processes in the current session lose their controlling terminal.
-.SS "Process group and session ID"
+.SS Process group and session ID
.TP
.BI "TIOCGPGRP pid_t *" argp
When successful, equivalent to
in case the terminal is not a master pseudoterminal
and not our controlling terminal.
Strange.
-.SS "Exclusive mode"
+.SS Exclusive mode
.TP
.B "TIOCEXCL void"
Put the terminal into exclusive mode.
operations on the terminal are permitted.
(They will fail with
.BR EBUSY ,
-except for root, that is, a process with the
+except for a process with the
.BR CAP_SYS_ADMIN
capability.)
.TP
.B "TIOCNXCL void"
Disable exclusive mode.
-.SS "Line discipline"
+.SS Line discipline
.TP
.BI "TIOCGETD int *" argp
Get the line discipline of the terminal.
.TP
.BI "TIOCSETD const int *" argp
Set the line discipline of the terminal.
-.SS "Psuedoterminal ioctls"
+.SS Pseudoterminal ioctls
.TP
.BI "TIOCPKT const int *" argp
Enable (when
.BR TIOCUCNTL ,
.B TIOCREMOTE
have not been implemented under Linux.
-.SS "Modem control"
+.SS Modem control
.TP
.BI "TIOCMGET int *" argp
get the status of modem bits.
TIOCM_RI see TIOCM_RNG
TIOCM_DSR DSR (data set ready)
.fi
-.SS "Marking a line as local"
+.SS Marking a line as local
.TP
.BI "TIOCGSOFTCAR int *" argp
("Get software carrier flag")
is set, the line behaves as if DCD is always asserted.
The software carrier flag is usually turned on for local devices,
and is off for lines with modems.
-.SS "Linux-specific"
+.SS Linux-specific
For the
.B TIOCLINUX
ioctl, see
.BR console_ioctl (4).
-.SS "Kernel debugging"
+.SS Kernel debugging
.B "#include <linux/tty.h>"
.TP
.BI "TIOCTTYGSTRUCT struct tty_struct *" argp
.\" .TP
.\" .BI "TIOCSSERIAL const struct serial_struct *" argp
.\" Set serial info.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
The
.BR ioctl (2)
system call returns 0 on success.
-On error it returns \-1 and sets
+On error, it returns \-1 and sets
.I errno
appropriately.
.SH ERRORS
close(fd);
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR ioctl (2),
.BR termios (3),
.BR console_ioctl (4),
.\" TIOCSERGETMULTI struct serial_multiport_struct *
.\" TIOCSERSETMULTI const struct serial_multiport_struct *
.\" TIOCGSERIAL, TIOCSSERIAL (see above)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.