1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2003, 2007 Oswald Buddenhagen <ossi@kde.org>
4 SPDX-FileCopyrightText: 2022 Harald Sitter <sitter@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef kpty_h
10#define kpty_h
11
12#include "kpty_export.h"
13
14#include <qglobal.h>
15
16#include <memory>
17
18class KPtyPrivate;
19struct termios;
20
21/**
22 * Provides primitives for opening & closing a pseudo TTY pair, assigning the
23 * controlling TTY, utmp registration and setting various terminal attributes.
24 */
25class KPTY_EXPORT KPty
26{
27 Q_DECLARE_PRIVATE(KPty)
28
29public:
30 /**
31 * Constructor
32 */
33 KPty();
34
35 /**
36 * Destructor:
37 *
38 * If the pty is still open, it will be closed. Note, however, that
39 * an utmp registration is @em not undone.
40 */
41 ~KPty();
42
43 KPty(const KPty &) = delete;
44 KPty &operator=(const KPty &) = delete;
45
46 /**
47 * Create a pty master/slave pair.
48 *
49 * @return true if a pty pair was successfully opened
50 */
51 bool open();
52
53 /**
54 * Open using an existing pty master.
55 *
56 * @param fd an open pty master file descriptor.
57 * The ownership of the fd remains with the caller;
58 * it will not be automatically closed at any point.
59 * @return true if a pty pair was successfully opened
60 */
61 bool open(int fd);
62
63 /**
64 * Close the pty master/slave pair.
65 */
66 void close();
67
68 /**
69 * Close the pty slave descriptor.
70 *
71 * When creating the pty, KPty also opens the slave and keeps it open.
72 * Consequently the master will never receive an EOF notification.
73 * Usually this is the desired behavior, as a closed pty slave can be
74 * reopened any time - unlike a pipe or socket. However, in some cases
75 * pipe-alike behavior might be desired.
76 *
77 * After this function was called, slaveFd() and setCTty() cannot be
78 * used.
79 */
80 void closeSlave();
81
82 /**
83 * Open the pty slave descriptor.
84 *
85 * This undoes the effect of closeSlave().
86 *
87 * @return true if the pty slave was successfully opened
88 */
89 bool openSlave();
90
91 /**
92 * @brief Whether this will be a controlling terminal
93 *
94 * This is on by default.
95 * Disabling the controllig aspect only makes sense if another process will
96 * take over control or there is nothing to control or for technical reasons
97 * control cannot be set (this notably is the case with flatpak-spawn when
98 * used inside a sandbox).
99 *
100 * @param enable whether to enable ctty set up
101 */
102 void setCTtyEnabled(bool enable);
103
104 /**
105 * Creates a new session and process group and makes this pty the
106 * controlling tty.
107 */
108 void setCTty();
109
110 /**
111 * Creates an utmp entry for the tty.
112 * This function must be called after calling setCTty and
113 * making this pty the stdin.
114 * @param user the user to be logged on
115 * @param remotehost the host from which the login is coming. This is
116 * @em not the local host. For remote logins it should be the hostname
117 * of the client. For local logins from inside an X session it should
118 * be the name of the X display. Otherwise it should be empty.
119 */
120 void login(const char *user = nullptr, const char *remotehost = nullptr);
121
122 /**
123 * Removes the utmp entry for this tty.
124 */
125 void logout();
126
127 /**
128 * Wrapper around tcgetattr(3).
129 *
130 * This function can be used only while the PTY is open.
131 * You will need an #include &lt;termios.h&gt; to do anything useful
132 * with it.
133 *
134 * @param ttmode a pointer to a termios structure.
135 * Note: when declaring ttmode, @c struct @c ::termios must be used -
136 * without the '::' some version of HP-UX thinks, this declares
137 * the struct in your class, in your method.
138 * @return @c true on success, false otherwise
139 */
140 bool tcGetAttr(struct ::termios *ttmode) const;
141
142 /**
143 * Wrapper around tcsetattr(3) with mode TCSANOW.
144 *
145 * This function can be used only while the PTY is open.
146 *
147 * @param ttmode a pointer to a termios structure.
148 * @return @c true on success, false otherwise. Note that success means
149 * that @em at @em least @em one attribute could be set.
150 */
151 bool tcSetAttr(struct ::termios *ttmode);
152
153 /**
154 * Change the logical (screen) size of the pty.
155 * The default is 24 lines by 80 columns in characters, and zero pixels.
156 *
157 * This function can be used only while the PTY is open.
158 *
159 * @param lines the number of character rows
160 * @param columns the number of character columns
161 * @param height the view height in pixels
162 * @param width the view width in pixels
163 * @return @c true on success, false otherwise
164 *
165 * @since 5.93
166 */
167 bool setWinSize(int lines, int columns, int height, int width);
168
169 /**
170 * @overload
171 * Change the logical (screen) size of the pty.
172 * The pixel size is set to zero.
173 */
174 bool setWinSize(int lines, int columns);
175
176 /**
177 * Set whether the pty should echo input.
178 *
179 * Echo is on by default.
180 * If the output of automatically fed (non-interactive) PTY clients
181 * needs to be parsed, disabling echo often makes it much simpler.
182 *
183 * This function can be used only while the PTY is open.
184 *
185 * @param echo true if input should be echoed.
186 * @return @c true on success, false otherwise
187 */
188 bool setEcho(bool echo);
189
190 /**
191 * @return the name of the slave pty device.
192 *
193 * This function should be called only while the pty is open.
194 */
195 const char *ttyName() const;
196
197 /**
198 * @return the file descriptor of the master pty
199 *
200 * This function should be called only while the pty is open.
201 */
202 int masterFd() const;
203
204 /**
205 * @return the file descriptor of the slave pty
206 *
207 * This function should be called only while the pty slave is open.
208 */
209 int slaveFd() const;
210
211protected:
212 /**
213 * @internal
214 */
215 KPTY_NO_EXPORT explicit KPty(KPtyPrivate *d);
216
217 /**
218 * @internal
219 */
220 std::unique_ptr<KPtyPrivate> const d_ptr;
221};
222
223#endif
224

source code of kpty/src/kpty.h