2
* This file is a part of QTerminal - http://gitorious.org/qterminal
4
* This file was un-linked from KDE and modified
5
* by Maxim Bourmistrov <maxim@unixconn.com>
10
This file is part of the KDE libraries
12
Copyright (C) 2007 Oswald Buddenhagen <ossi@kde.org>
14
This library is free software; you can redistribute it and/or
15
modify it under the terms of the GNU Library General Public
16
License as published by the Free Software Foundation; either
17
version 2 of the License, or (at your option) any later version.
19
This library is distributed in the hope that it will be useful,
20
but WITHOUT ANY WARRANTY; without even the implied warranty of
21
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22
Library General Public License for more details.
24
You should have received a copy of the GNU Library General Public License
25
along with this library; see the file COPYING.LIB. If not, write to
26
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
27
Boston, MA 02110-1301, USA.
33
//#include <kdecore_export.h>
37
class KProcessPrivate;
40
* \class KProcess kprocess.h <KProcess>
42
* Child process invocation, monitoring and control.
44
* This class extends QProcess by some useful functionality, overrides
45
* some defaults with saner values and wraps parts of the API into a more
47
* This is the preferred way of spawning child processes in KDE; don't
48
* use QProcess directly.
50
* @author Oswald Buddenhagen <ossi@kde.org>
52
class KProcess : public QProcess
55
Q_DECLARE_PRIVATE(KProcess)
60
* Modes in which the output channels can be opened.
62
enum OutputChannelMode {
63
SeparateChannels = QProcess::SeparateChannels,
64
/**< Standard output and standard error are handled by KProcess
65
as separate channels */
66
MergedChannels = QProcess::MergedChannels,
67
/**< Standard output and standard error are handled by KProcess
69
ForwardedChannels = QProcess::ForwardedChannels,
70
/**< Both standard output and standard error are forwarded
71
to the parent process' respective channel */
73
/**< Only standard output is handled; standard error is forwarded */
74
OnlyStderrChannel /**< Only standard error is handled; standard output is forwarded */
80
explicit KProcess(QObject *parent = 0);
88
* Set how to handle the output channels of the child process.
90
* The default is ForwardedChannels, which is unlike in QProcess.
91
* Do not request more than you actually handle, as this output is
92
* simply lost otherwise.
94
* This function must be called before starting the process.
96
* @param mode the output channel handling mode
98
void setOutputChannelMode(OutputChannelMode mode);
101
* Query how the output channels of the child process are handled.
103
* @return the output channel handling mode
105
OutputChannelMode outputChannelMode() const;
108
* Set the QIODevice open mode the process will be opened in.
110
* This function must be called before starting the process, obviously.
112
* @param mode the open mode. Note that this mode is automatically
113
* "reduced" according to the channel modes and redirections.
114
* The default is QIODevice::ReadWrite.
116
void setNextOpenMode(QIODevice::OpenMode mode);
119
* Adds the variable @p name to the process' environment.
121
* This function must be called before starting the process.
123
* @param name the name of the environment variable
124
* @param value the new value for the environment variable
125
* @param overwrite if @c false and the environment variable is already
126
* set, the old value will be preserved
128
void setEnv(const QString &name, const QString &value, bool overwrite = true);
131
* Removes the variable @p name from the process' environment.
133
* This function must be called before starting the process.
135
* @param name the name of the environment variable
137
void unsetEnv(const QString &name);
140
* Empties the process' environment.
142
* Note that LD_LIBRARY_PATH/DYLD_LIBRARY_PATH is automatically added
145
* This function must be called before starting the process.
147
void clearEnvironment();
150
* Set the program and the command line arguments.
152
* This function must be called before starting the process, obviously.
154
* @param exe the program to execute
155
* @param args the command line arguments for the program,
156
* one per list element
158
void setProgram(const QString &exe, const QStringList &args = QStringList());
163
* @param argv the program to execute and the command line arguments
164
* for the program, one per list element
166
void setProgram(const QStringList &argv);
169
* Append an element to the command line argument list for this process.
171
* If no executable is set yet, it will be set instead.
173
* For example, doing an "ls -l /usr/local/bin" can be achieved by:
176
* p << "ls" << "-l" << "/usr/local/bin";
180
* This function must be called before starting the process, obviously.
182
* @param arg the argument to add
183
* @return a reference to this KProcess
185
KProcess &operator<<(const QString& arg);
190
* @param args the arguments to add
191
* @return a reference to this KProcess
193
KProcess &operator<<(const QStringList& args);
196
* Clear the program and command line argument list.
201
* Set a command to execute through a shell (a POSIX sh on *NIX
202
* and cmd.exe on Windows).
204
* Using this for anything but user-supplied commands is usually a bad
205
* idea, as the command's syntax depends on the platform.
206
* Redirections including pipes, etc. are better handled by the
207
* respective functions provided by QProcess.
209
* If KProcess determines that the command does not really need a
210
* shell, it will trasparently execute it without one for performance
213
* This function must be called before starting the process, obviously.
215
* @param cmd the command to execute through a shell.
216
* The caller must make sure that all filenames etc. are properly
217
* quoted when passed as argument. Failure to do so often results in
218
* serious security holes. See KShell::quoteArg().
220
void setShellCommand(const QString &cmd);
223
* Obtain the currently set program and arguments.
225
* @return a list, the first element being the program, the remaining ones
226
* being command line arguments to the program.
228
QStringList program() const;
233
* @see QProcess::start(const QString &, const QStringList &, OpenMode)
238
* Start the process, wait for it to finish, and return the exit code.
240
* This method is roughly equivalent to the sequence:
243
* waitForFinished(msecs);
247
* Unlike the other execute() variants this method is not static,
248
* so the process can be parametrized properly and talked to.
250
* @param msecs time to wait for process to exit before killing it
251
* @return -2 if the process could not be started, -1 if it crashed,
252
* otherwise its exit code
254
int execute(int msecs = -1);
259
* @param exe the program to execute
260
* @param args the command line arguments for the program,
261
* one per list element
262
* @param msecs time to wait for process to exit before killing it
263
* @return -2 if the process could not be started, -1 if it crashed,
264
* otherwise its exit code
266
static int execute(const QString &exe, const QStringList &args = QStringList(), int msecs = -1);
271
* @param argv the program to execute and the command line arguments
272
* for the program, one per list element
273
* @param msecs time to wait for process to exit before killing it
274
* @return -2 if the process could not be started, -1 if it crashed,
275
* otherwise its exit code
277
static int execute(const QStringList &argv, int msecs = -1);
280
* Start the process and detach from it. See QProcess::startDetached()
283
* Unlike the other startDetached() variants this method is not static,
284
* so the process can be parametrized properly.
285
* @note Currently, only the setProgram()/setShellCommand() and
286
* setWorkingDirectory() parametrizations are supported.
288
* The KProcess object may be re-used immediately after calling this
291
* @return the PID of the started process or 0 on error
298
* @param exe the program to start
299
* @param args the command line arguments for the program,
300
* one per list element
301
* @return the PID of the started process or 0 on error
303
static int startDetached(const QString &exe, const QStringList &args = QStringList());
308
* @param argv the program to start and the command line arguments
309
* for the program, one per list element
310
* @return the PID of the started process or 0 on error
312
static int startDetached(const QStringList &argv);
315
* Obtain the process' ID as known to the system.
317
* Unlike with QProcess::pid(), this is a real PID also on Windows.
319
* This function can be called only while the process is running.
320
* It cannot be applied to detached processes.
322
* @return the process ID
330
KProcess(KProcessPrivate *d, QObject *parent);
335
KProcessPrivate * const d_ptr;
339
using QProcess::setReadChannelMode;
340
using QProcess::readChannelMode;
341
using QProcess::setProcessChannelMode;
342
using QProcess::processChannelMode;
344
Q_PRIVATE_SLOT(d_func(), void _k_forwardStdout())
345
Q_PRIVATE_SLOT(d_func(), void _k_forwardStderr())
348
/* ----------- kprocess_p.h ---------------- */
349
class KProcessPrivate {
351
Q_DECLARE_PUBLIC(KProcess)
355
openMode(QIODevice::ReadWrite)
358
void writeAll(const QByteArray &buf, int fd);
359
void forwardStd(KProcess::ProcessChannel good, int fd);
360
void _k_forwardStdout();
361
void _k_forwardStderr();
365
KProcess::OutputChannelMode outputChannelMode;
366
QIODevice::OpenMode openMode;
370
/* ------------------------------------------- */