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