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
26struct KPtyPrivate;
27struct 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 */
33class KPTY_EXPORT KPty {
34 Q_DECLARE_PRIVATE(KPty)
35
36public:
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 &lt;termios.h&gt; 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
192protected:
193 /**
194 * @internal
195 */
196 KPty(KPtyPrivate *d);
197
198 /**
199 * @internal
200 */
201 KPtyPrivate * const d_ptr;
202};
203
204#endif
205
206