1/*
2 This file is part of the KDE libraries
3
4 Copyright (C) 2007 Oswald Buddenhagen <ossi@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KPTYPROCESS_H
23#define KPTYPROCESS_H
24
25#include <kprocess.h>
26
27#include "kpty_export.h"
28
29class KPtyDevice;
30
31struct KPtyProcessPrivate;
32
33/**
34 * This class extends KProcess by support for PTYs (pseudo TTYs).
35 *
36 * The PTY is opened as soon as the class is instantiated. Verify that
37 * it was opened successfully by checking that pty()->masterFd() is not -1.
38 *
39 * The PTY is always made the process' controlling TTY.
40 * Utmp registration and connecting the stdio handles to the PTY are optional.
41 *
42 * No attempt to integrate with QProcess' waitFor*() functions was made,
43 * for it is impossible. Note that execute() does not work with the PTY, too.
44 * Use the PTY device's waitFor*() functions or use it asynchronously.
45 *
46 * @author Oswald Buddenhagen <ossi@kde.org>
47 */
48class KPTY_EXPORT KPtyProcess : public KProcess
49{
50 Q_OBJECT
51 Q_DECLARE_PRIVATE(KPtyProcess)
52
53public:
54 enum PtyChannelFlag {
55 NoChannels = 0, /**< The PTY is not connected to any channel. */
56 StdinChannel = 1, /**< Connect PTY to stdin. */
57 StdoutChannel = 2, /**< Connect PTY to stdout. */
58 StderrChannel = 4, /**< Connect PTY to stderr. */
59 AllOutputChannels = 6, /**< Connect PTY to all output channels. */
60 AllChannels = 7 /**< Connect PTY to all channels. */
61 };
62
63 Q_DECLARE_FLAGS(PtyChannels, PtyChannelFlag)
64
65 /**
66 * Constructor
67 */
68 explicit KPtyProcess(QObject *parent = 0);
69
70 /**
71 * Construct a process using an open pty master.
72 *
73 * @param ptyMasterFd an open pty master file descriptor.
74 * The process does not take ownership of the descriptor;
75 * it will not be automatically closed at any point.
76 */
77 KPtyProcess(int ptyMasterFd, QObject *parent = 0);
78
79 /**
80 * Destructor
81 */
82 virtual ~KPtyProcess();
83
84 /**
85 * Set to which channels the PTY should be assigned.
86 *
87 * This function must be called before starting the process.
88 *
89 * @param channels the output channel handling mode
90 */
91 void setPtyChannels(PtyChannels channels);
92
93 /**
94 * Query to which channels the PTY is assigned.
95 *
96 * @return the output channel handling mode
97 */
98 PtyChannels ptyChannels() const;
99
100 /**
101 * Set whether to register the process as a TTY login in utmp.
102 *
103 * Utmp is disabled by default.
104 * It should enabled for interactively fed processes, like terminal
105 * emulations.
106 *
107 * This function must be called before starting the process.
108 *
109 * @param value whether to register in utmp.
110 */
111 void setUseUtmp(bool value);
112
113 /**
114 * Get whether to register the process as a TTY login in utmp.
115 *
116 * @return whether to register in utmp
117 */
118 bool isUseUtmp() const;
119
120 /**
121 * Get the PTY device of this process.
122 *
123 * @return the PTY device
124 */
125 KPtyDevice *pty() const;
126
127protected:
128 /**
129 * @reimp
130 */
131 virtual void setupChildProcess();
132
133private:
134 Q_PRIVATE_SLOT(d_func(), void _k_onStateChanged(QProcess::ProcessState))
135};
136
137Q_DECLARE_OPERATORS_FOR_FLAGS(KPtyProcess::PtyChannels)
138
139#endif
140