Debian Codegraph @

upstream/debian-trixie/man2/TIOCPKT.2const

raw
1 '\" t
2 .\" Copyright 2002, Walter Harms <[email protected]>
3 .\" Copyright 2002, Andries Brouwer <[email protected]>
4 .\" Copyright 2024, Alejandro Colomar <[email protected]>
5 .\"
6 .\" SPDX-License-Identifier: GPL-1.0-or-later
7 .\"
8 .TH TIOCPKT 2const 2024-06-15 "Linux man-pages 6.9.1"
9 .SH NAME
10 TIOCPKT,
11 TIOCGPKT,
12 TIOCSPTLCK,
13 TIOCGPTLCK,
14 TIOCGPTPEER
15 \-
16 pseudoterminal ioctls
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .BR "#include <asm/termbits.h>" " /* Definition of " TIOC* " constants */"
23 .B #include <sys/ioctl.h>
24 .P
25 .BI "int ioctl(int " fd ", TIOCPKT, const int *" mode );
26 .BI "int ioctl(int " fd ", TIOCPKT, int *" mode );
27 .P
28 .BI "int ioctl(int " fd ", TIOCSPTLCK, const int *" lock );
29 .BI "int ioctl(int " fd ", TIOCGPTLCK, int *" lock );
30 .P
31 .BI "int ioctl(int " fd ", TIOCGPTPEER, int " flags );
32 .fi
33 .SH DESCRIPTION
34 .TP
35 .B TIOCPKT
36 Enable (when
37 .RI * mode
38 is nonzero) or disable packet mode.
39 Can be applied to the master side of a pseudoterminal only (and will return
40 .B ENOTTY
41 otherwise).
42 In packet mode, each subsequent
43 .BR read (2)
44 will return a packet that either contains a single nonzero control byte,
45 or has a single byte containing zero (\[aq]\[rs]0\[aq]) followed by data
46 written on the slave side of the pseudoterminal.
47 If the first byte is not
48 .B TIOCPKT_DATA
49 (0), it is an OR of one
50 or more of the following bits:
51 .IP
52 .ad l
53 .TS
54 lb l.
55 TIOCPKT_FLUSHREAD T{
56 The read queue for the terminal is flushed.
57 T}
58 TIOCPKT_FLUSHWRITE T{
59 The write queue for the terminal is flushed.
60 T}
61 TIOCPKT_STOP T{
62 Output to the terminal is stopped.
63 T}
64 TIOCPKT_START T{
65 Output to the terminal is restarted.
66 T}
67 TIOCPKT_DOSTOP T{
68 The start and stop characters are \fB\[ha]S\fP/\fB\[ha]Q\fP.
69 T}
70 TIOCPKT_NOSTOP T{
71 The start and stop characters are not \fB\[ha]S\fP/\fB\[ha]Q\fP.
72 T}
73 .TE
74 .ad
75 .IP
76 While packet mode is in use, the presence
77 of control status information to be read
78 from the master side may be detected by a
79 .BR select (2)
80 for exceptional conditions or a
81 .BR poll (2)
82 for the
83 .B POLLPRI
84 event.
85 .IP
86 This mode is used by
87 .BR rlogin (1)
88 and
89 .BR rlogind (8)
90 to implement a remote-echoed,
91 locally \fB\[ha]S\fP/\fB\[ha]Q\fP flow-controlled remote login.
92 .TP
93 .B TIOCGPKT
94 Return the current packet mode setting in the integer pointed to by
95 .IR mode .
96 .TP
97 .B TIOCSPTLCK
98 Set (if
99 .I *lock
100 is nonzero) or remove (if
101 .I *lock
102 is zero) the lock on the pseudoterminal slave device.
103 (See also
104 .BR unlockpt (3).)
105 .TP
106 .B TIOCGPTLCK
107 Place the current lock state of the pseudoterminal slave device
108 in the location pointed to by
109 .IR lock .
110 .TP
111 .B TIOCGPTPEER
112 Given a file descriptor in
113 .I fd
114 that refers to a pseudoterminal master,
115 open (with the given
116 .BR open (2)-style
117 .IR flags )
118 and return a new file descriptor that refers to the peer
119 pseudoterminal slave device.
120 This operation can be performed
121 regardless of whether the pathname of the slave device
122 is accessible through the calling process's mount namespace.
123 .IP
124 Security-conscious programs interacting with namespaces may wish to use this
125 operation rather than
126 .BR open (2)
127 with the pathname returned by
128 .BR ptsname (3),
129 and similar library functions that have insecure APIs.
130 (For example, confusion can occur in some cases using
131 .BR ptsname (3)
132 with a pathname where a devpts filesystem
133 has been mounted in a different mount namespace.)
134 .SH RETURN VALUE
135 On success,
136 0 is returned.
137 On error,
138 \-1 is returned, and
139 .I errno
140 is set to indicate the error.
141 .SH ERRORS
142 .TP
143 .B ENOTTY
144 .SH HISTORY
145 .TP
146 .B TIOCGPKT
147 Linux 3.8.
148 .TP
149 .B TIOCGPTLCK
150 Linux 3.8.
151 .TP
152 .B TIOCGPTPEER
153 .\" linux.git commit 54ebbfb1603415d9953c150535850d30609ef077
154 Linux 4.13.
155 .P
156 The BSD ioctls
157 .BR TIOCSTOP ,
158 .BR TIOCSTART ,
159 .BR TIOCUCNTL ,
160 and
161 .B TIOCREMOTE
162 have not been implemented under Linux.
163 .SH SEE ALSO
164 .BR ioctl (2),
165 .BR ioctl_tty (2)