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 | |
18 | class KPtyPrivate; |
19 | struct 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 | */ |
28 | class KPTY_EXPORT KPty |
29 | { |
30 | Q_DECLARE_PRIVATE(KPty) |
31 | |
32 | public: |
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 | |
224 | protected: |
225 | KPTY_NO_EXPORT explicit KPty(KPtyPrivate *d); |
226 | |
227 | std::unique_ptr<KPtyPrivate> const d_ptr; |
228 | }; |
229 | |
230 | #endif |
231 | |