'\" t
.\" Copyright 2002, Walter Harms <walter.harms@informatik.uni-oldenburg.de>
.\" Copyright 2002, Andries Brouwer <aeb@cwi.nl>
.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: GPL-1.0-or-later
.\"
.TH TIOCPKT 2const 2024-06-15 "Linux man-pages 6.9.1"
.SH NAME
TIOCPKT,
TIOCGPKT,
TIOCSPTLCK,
TIOCGPTLCK,
TIOCGPTPEER
\-
pseudoterminal ioctls
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.BR "#include <asm/termbits.h>" "  /* Definition of " TIOC* " constants */"
.B #include <sys/ioctl.h>
.P
.BI "int ioctl(int " fd ", TIOCPKT, const int *" mode );
.BI "int ioctl(int " fd ", TIOCPKT, int *" mode );
.P
.BI "int ioctl(int " fd ", TIOCSPTLCK, const int *" lock );
.BI "int ioctl(int " fd ", TIOCGPTLCK, int *" lock );
.P
.BI "int ioctl(int " fd ", TIOCGPTPEER, int " flags );
.fi
.SH DESCRIPTION
.TP
.B TIOCPKT
Enable (when
.RI * mode
is nonzero) or disable packet mode.
Can be applied to the master side of a pseudoterminal only (and will return
.B ENOTTY
otherwise).
In packet mode, each subsequent
.BR read (2)
will return a packet that either contains a single nonzero control byte,
or has a single byte containing zero (\[aq]\[rs]0\[aq]) followed by data
written on the slave side of the pseudoterminal.
If the first byte is not
.B TIOCPKT_DATA
(0), it is an OR of one
or more of the following bits:
.IP
.ad l
.TS
lb l.
TIOCPKT_FLUSHREAD	T{
The read queue for the terminal is flushed.
T}
TIOCPKT_FLUSHWRITE	T{
The write queue for the terminal is flushed.
T}
TIOCPKT_STOP	T{
Output to the terminal is stopped.
T}
TIOCPKT_START	T{
Output to the terminal is restarted.
T}
TIOCPKT_DOSTOP	T{
The start and stop characters are \fB\[ha]S\fP/\fB\[ha]Q\fP.
T}
TIOCPKT_NOSTOP	T{
The start and stop characters are not \fB\[ha]S\fP/\fB\[ha]Q\fP.
T}
.TE
.ad
.IP
While packet mode is in use, the presence
of control status information to be read
from the master side may be detected by a
.BR select (2)
for exceptional conditions or a
.BR poll (2)
for the
.B POLLPRI
event.
.IP
This mode is used by
.BR rlogin (1)
and
.BR rlogind (8)
to implement a remote-echoed,
locally \fB\[ha]S\fP/\fB\[ha]Q\fP flow-controlled remote login.
.TP
.B TIOCGPKT
Return the current packet mode setting in the integer pointed to by
.IR mode .
.TP
.B TIOCSPTLCK
Set (if
.I *lock
is nonzero) or remove (if
.I *lock
is zero) the lock on the pseudoterminal slave device.
(See also
.BR unlockpt (3).)
.TP
.B TIOCGPTLCK
Place the current lock state of the pseudoterminal slave device
in the location pointed to by
.IR lock .
.TP
.B TIOCGPTPEER
Given a file descriptor in
.I fd
that refers to a pseudoterminal master,
open (with the given
.BR open (2)-style
.IR flags )
and return a new file descriptor that refers to the peer
pseudoterminal slave device.
This operation can be performed
regardless of whether the pathname of the slave device
is accessible through the calling process's mount namespace.
.IP
Security-conscious programs interacting with namespaces may wish to use this
operation rather than
.BR open (2)
with the pathname returned by
.BR ptsname (3),
and similar library functions that have insecure APIs.
(For example, confusion can occur in some cases using
.BR ptsname (3)
with a pathname where a devpts filesystem
has been mounted in a different mount namespace.)
.SH RETURN VALUE
On success,
0 is returned.
On error,
\-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B ENOTTY
.SH HISTORY
.TP
.B TIOCGPKT
Linux 3.8.
.TP
.B TIOCGPTLCK
Linux 3.8.
.TP
.B TIOCGPTPEER
.\" linux.git commit 54ebbfb1603415d9953c150535850d30609ef077
Linux 4.13.
.P
The BSD ioctls
.BR TIOCSTOP ,
.BR TIOCSTART ,
.BR TIOCUCNTL ,
and
.B TIOCREMOTE
have not been implemented under Linux.
.SH SEE ALSO
.BR ioctl (2),
.BR ioctl_tty (2)