1 | /* This file is part of the KDE libraries |
2 | |
3 | Copyright (C) 2003,2007 Oswald Buddenhagen <ossi@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License as published by the Free Software Foundation; either |
8 | version 2 of the License, or (at your option) any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Library General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to |
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef kpty_h |
22 | #define kpty_h |
23 | |
24 | #include "kpty_export.h" |
25 | |
26 | struct KPtyPrivate; |
27 | struct termios; |
28 | |
29 | /** |
30 | * Provides primitives for opening & closing a pseudo TTY pair, assigning the |
31 | * controlling TTY, utmp registration and setting various terminal attributes. |
32 | */ |
33 | class KPTY_EXPORT KPty { |
34 | Q_DECLARE_PRIVATE(KPty) |
35 | |
36 | public: |
37 | |
38 | /** |
39 | * Constructor |
40 | */ |
41 | KPty(); |
42 | |
43 | /** |
44 | * Destructor: |
45 | * |
46 | * If the pty is still open, it will be closed. Note, however, that |
47 | * an utmp registration is @em not undone. |
48 | */ |
49 | ~KPty(); |
50 | |
51 | /** |
52 | * Create a pty master/slave pair. |
53 | * |
54 | * @return true if a pty pair was successfully opened |
55 | */ |
56 | bool open(); |
57 | |
58 | /** |
59 | * Open using an existing pty master. |
60 | * |
61 | * @param fd an open pty master file descriptor. |
62 | * The ownership of the fd remains with the caller; |
63 | * it will not be automatically closed at any point. |
64 | * @return true if a pty pair was successfully opened |
65 | */ |
66 | bool open(int fd); |
67 | |
68 | /** |
69 | * Close the pty master/slave pair. |
70 | */ |
71 | void close(); |
72 | |
73 | /** |
74 | * Close the pty slave descriptor. |
75 | * |
76 | * When creating the pty, KPty also opens the slave and keeps it open. |
77 | * Consequently the master will never receive an EOF notification. |
78 | * Usually this is the desired behavior, as a closed pty slave can be |
79 | * reopened any time - unlike a pipe or socket. However, in some cases |
80 | * pipe-alike behavior might be desired. |
81 | * |
82 | * After this function was called, slaveFd() and setCTty() cannot be |
83 | * used. |
84 | */ |
85 | void closeSlave(); |
86 | |
87 | /** |
88 | * Open the pty slave descriptor. |
89 | * |
90 | * This undoes the effect of closeSlave(). |
91 | * |
92 | * @return true if the pty slave was successfully opened |
93 | */ |
94 | bool openSlave(); |
95 | |
96 | /** |
97 | * Creates a new session and process group and makes this pty the |
98 | * controlling tty. |
99 | */ |
100 | void setCTty(); |
101 | |
102 | /** |
103 | * Creates an utmp entry for the tty. |
104 | * This function must be called after calling setCTty and |
105 | * making this pty the stdin. |
106 | * @param user the user to be logged on |
107 | * @param remotehost the host from which the login is coming. This is |
108 | * @em not the local host. For remote logins it should be the hostname |
109 | * of the client. For local logins from inside an X session it should |
110 | * be the name of the X display. Otherwise it should be empty. |
111 | */ |
112 | void login(const char *user = 0, const char *remotehost = 0); |
113 | |
114 | /** |
115 | * Removes the utmp entry for this tty. |
116 | */ |
117 | void logout(); |
118 | |
119 | /** |
120 | * Wrapper around tcgetattr(3). |
121 | * |
122 | * This function can be used only while the PTY is open. |
123 | * You will need an #include <termios.h> to do anything useful |
124 | * with it. |
125 | * |
126 | * @param ttmode a pointer to a termios structure. |
127 | * Note: when declaring ttmode, @c struct @c ::termios must be used - |
128 | * without the '::' some version of HP-UX thinks, this declares |
129 | * the struct in your class, in your method. |
130 | * @return @c true on success, false otherwise |
131 | */ |
132 | bool tcGetAttr(struct ::termios *ttmode) const; |
133 | |
134 | /** |
135 | * Wrapper around tcsetattr(3) with mode TCSANOW. |
136 | * |
137 | * This function can be used only while the PTY is open. |
138 | * |
139 | * @param ttmode a pointer to a termios structure. |
140 | * @return @c true on success, false otherwise. Note that success means |
141 | * that @em at @em least @em one attribute could be set. |
142 | */ |
143 | bool tcSetAttr(struct ::termios *ttmode); |
144 | |
145 | /** |
146 | * Change the logical (screen) size of the pty. |
147 | * The default is 24 lines by 80 columns. |
148 | * |
149 | * This function can be used only while the PTY is open. |
150 | * |
151 | * @param lines the number of rows |
152 | * @param columns the number of columns |
153 | * @return @c true on success, false otherwise |
154 | */ |
155 | bool setWinSize(int lines, int columns); |
156 | |
157 | /** |
158 | * Set whether the pty should echo input. |
159 | * |
160 | * Echo is on by default. |
161 | * If the output of automatically fed (non-interactive) PTY clients |
162 | * needs to be parsed, disabling echo often makes it much simpler. |
163 | * |
164 | * This function can be used only while the PTY is open. |
165 | * |
166 | * @param echo true if input should be echoed. |
167 | * @return @c true on success, false otherwise |
168 | */ |
169 | bool setEcho(bool echo); |
170 | |
171 | /** |
172 | * @return the name of the slave pty device. |
173 | * |
174 | * This function should be called only while the pty is open. |
175 | */ |
176 | const char *ttyName() const; |
177 | |
178 | /** |
179 | * @return the file descriptor of the master pty |
180 | * |
181 | * This function should be called only while the pty is open. |
182 | */ |
183 | int masterFd() const; |
184 | |
185 | /** |
186 | * @return the file descriptor of the slave pty |
187 | * |
188 | * This function should be called only while the pty slave is open. |
189 | */ |
190 | int slaveFd() const; |
191 | |
192 | protected: |
193 | /** |
194 | * @internal |
195 | */ |
196 | KPty(KPtyPrivate *d); |
197 | |
198 | /** |
199 | * @internal |
200 | */ |
201 | KPtyPrivate * const d_ptr; |
202 | }; |
203 | |
204 | #endif |
205 | |
206 | |