KPty

kpty.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2003, 2007 Oswald Buddenhagen <[email protected]>
4  SPDX-FileCopyrightText: 2022 Harald Sitter <[email protected]>
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  * Provides primitives for opening & closing a pseudo TTY pair, assigning the
23  * controlling TTY, utmp registration and setting various terminal attributes.
24  */
25 class KPTY_EXPORT KPty
26 {
27  Q_DECLARE_PRIVATE(KPty)
28 
29 public:
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 
211 protected:
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
const std::unique_ptr< KPtyPrivate > d_ptr
Definition: kpty.h:220
Provides primitives for opening & closing a pseudo TTY pair, assigning the controlling TTY,...
Definition: kpty.h:25
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Mar 26 2023 04:11:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.