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

source code of kpty/src/kpty.h