/* This file is part of the KDE libraries
Copyright (C) 1997 Christian Czezakte (e9025461@student.tuwien.ac.at)
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
//
// KPROCESS -- A class for handling child processes in KDE without
// having to take care of Un*x specific implementation details
//
// version 0.3.1, Jan 8th 1998
//
// (C) Christian Czezatke
// e9025461@student.tuwien.ac.at
//
#ifndef __kprocess_h__
#define __kprocess_h__
#include // for pid_t
#include
#include
#include
#include
#include
#include
class QSocketNotifier;
class KProcessPrivate;
/**
* Child process invocation, monitoring and control.
*
* @sect General usage and features
*
*This class allows a KDE application to start child processes without having
*to worry about UN*X signal handling issues and zombie process reaping.
*
*@see KProcIO
*
*Basically, this class distinguishes three different ways of running
*child processes:
*
*@li KProcess::DontCare -- The child process is invoked and both the child
*process and the parent process continue concurrently.
*
*Starting a DontCare child process means that the application is
*not interested in any notification to determine whether the
*child process has already exited or not.
*
*@li KProcess::NotifyOnExit -- The child process is invoked and both the
*child and the parent process run concurrently.
*
*When the child process exits, the KProcess instance
*corresponding to it emits the Qt signal @ref processExited().
*
*Since this signal is @em not emitted from within a UN*X
*signal handler, arbitrary function calls can be made.
*
*Be aware: When the KProcess objects gets destructed, the child
*process will be killed if it is still running!
*This means in particular, that you cannot use a KProcess on the stack
*with KProcess::NotifyOnExit.
*
*@li KProcess::Block -- The child process starts and the parent process
*is suspended until the child process exits. (@em Really not recommended
*for programs with a GUI.)
*
*KProcess also provides several functions for determining the exit status
*and the pid of the child process it represents.
*
*Furthermore it is possible to supply command-line arguments to the process
*in a clean fashion (no null -- terminated stringlists and such...)
*
*A small usage example:
*
*KProcess *proc = new KProcess;
*
**proc << "my_executable";
**proc << "These" << "are" << "the" << "command" << "line" << "args";
*QApplication::connect(proc, SIGNAL(processExited(KProcess *)),
* pointer_to_my_object, SLOT(my_objects_slot(KProcess *)));
*proc->start();
*
*
*This will start "my_executable" with the commandline arguments "These"...
*
*When the child process exits, the respective Qt signal will be emitted.
*
*@sect Communication with the child process
*
*KProcess supports communication with the child process through
*stdin/stdout/stderr.
*
*The following functions are provided for getting data from the child
*process or sending data to the child's stdin (For more information,
*have a look at the documentation of each function):
*
*@li bool @ref writeStdin(char *buffer, int buflen);
*@li -- Transmit data to the child process's stdin.
*
*@li bool @ref closeStdin();
*@li -- Closes the child process's stdin (which causes it to see an feof(stdin)).
*Returns false if you try to close stdin for a process that has been started
*without a communication channel to stdin.
*
*@li bool @ref closeStdout();
*@li -- Closes the child process's stdout.
*Returns false if you try to close stdout for a process that has been started
*without a communication channel to stdout.
*
*@li bool @ref closeStderr();
*@li -- Closes the child process's stderr.
*Returns false if you try to close stderr for a process that has been started
*without a communication channel to stderr.
*
*
*@sect QT signals:
*
*@li void @ref receivedStdout(KProcess *proc, char *buffer, int buflen);
*@li void @ref receivedStderr(KProcess *proc, char *buffer, int buflen);
*@li -- Indicates that new data has arrived from either the
*child process's stdout or stderr.
*
*@li void @ref wroteStdin(KProcess *proc);
*@li -- Indicates that all data that has been sent to the child process
*by a prior call to @ref writeStdin() has actually been transmitted to the
*client .
*
*@author Christian Czezakte e9025461@student.tuwien.ac.at
*
*
**/
class KProcess : public QObject
{
Q_OBJECT
public:
/**
* Modes in which the communication channel can be opened.
*
* If communication for more than one channel is required,
* the values have to be or'ed together, for example to get
* communication with stdout as well as with stdin, you would
* specify @p Stdin | @p Stdout
*
* If @p NoRead is specified in conjunction with @p Stdout,
* no data is actually read from @p Stdout but only
* the signal @ref childOutput(int fd) is emitted.
*/
enum Communication { NoCommunication = 0, Stdin = 1, Stdout = 2, Stderr = 4,
AllOutput = 6, All = 7,
NoRead };
/**
* Run-modes for a child process.
*/
enum RunMode {
/**
* The application does not receive notifications from the subprocess when
* it is finished or aborted.
*/
DontCare,
/**
* The application is notified when the subprocess dies.
*/
NotifyOnExit,
/**
* The application is suspended until the started process is finished.
*/
Block };
/**
* Constructor
*/
KProcess();
/**
*Destructor:
*
* If the process is running when the destructor for this class
* is called, the child process is killed with a SIGKILL, but
* only if the run mode is not of type @p DontCare.
* Processes started as @p DontCare keep running anyway.
*/
virtual ~KProcess();
/**
@deprecated
The use of this function is now deprecated. -- Please use the
"operator<<" instead of "setExecutable".
Sets the executable to be started with this KProcess object.
Returns false if the process is currently running (in that
case the executable remains unchanged.)
@see operator<<
*/
bool setExecutable(const QString& proc);
/**
* Sets the executable and the command line argument list for this process.
*
* For example, doing an "ls -l /usr/local/bin" can be achieved by:
*
* KProcess p;
* ...
* p << "ls" << "-l" << "/usr/local/bin"
*
*
* @param arg the argument to add
* @return a reference to this KProcess
**/
KProcess &operator<<(const QString& arg);
/**
* Similar to previous method, takes a char *, supposed to be in locale 8 bit already.
*/
KProcess &operator<<(const char * arg);
/**
* Similar to previous method, takes a QCString, supposed to be in locale 8 bit already.
* @param arg the argument to add
* @return a reference to this KProcess
*/
KProcess &operator<<(const QCString & arg);
/**
* Sets the executable and the command line argument list for this process,
* in a single method call, or add a list of arguments.
* @param arg the arguments to add
* @return a reference to this KProcess
**/
KProcess &operator<<(const QStringList& args);
/**
* Clear a command line argument list that has been set by using
* the "operator<<".
*/
void clearArguments();
/**
* Starts the process.
* For a detailed description of the
* various run modes and communication semantics, have a look at the
* general description of the KProcess class.
*
* The following problems could cause this function to
* return false:
*
* @li The process is already running.
* @li The command line argument list is empty.
* @li The starting of the process failed (could not fork).
* @li The executable was not found.
*
* @param runmode The Run-mode for the process.
* @param comm Specifies which communication links should be
* established to the child process (stdin/stdout/stderr). By default,
* no communication takes place and the respective communication
* signals will never get emitted.
*
* @return true on success, false on error
* (see above for error conditions)
**/
virtual bool start(RunMode runmode = NotifyOnExit,
Communication comm = NoCommunication);
/**
* Stop the process (by sending it a signal).
*
* @param signo The signal to send. The default is SIGTERM.
* @return true if the signal was delivered successfully.
*/
virtual bool kill(int signo = SIGTERM);
/**
* Checks whether the process is running.
* @return true if the process is (still) considered to be running
*/
bool isRunning() const;
/** Returns the process id of the process.
*
* If it is called after
* the process has exited, it returns the process id of the last
* child process that was created by this instance of KProcess.
*
* Calling it before any child process has been started by this
* KProcess instance causes pid() to return 0.
* @return the pid of the process or 0 if no process has been started yet.
**/
pid_t pid() const;
/**
* Use pid().
* @deprecated
*/
pid_t getPid() const { return pid(); }
/**
* Suspend processing of data from stdout of the child process.
*/
void suspend();
/**
* Resume processing of data from stdout of the child process.
*/
void resume();
/**
* @return true if the process has already finished and has exited
* "voluntarily", ie: it has not been killed by a signal.
*
* Note that you should check @ref KProcess::exitStatus() to determine
* whether the process completed its task successful or not.
*/
bool normalExit() const;
/**
* Returns the exit status of the process.
*
* Please use
* @ref KProcess::normalExit() to check whether the process has exited
* cleanly (i.e., @ref KProcess::normalExit() returns true) before calling
* this function because if the process did not exit normally,
* it does not have a valid exit status.
* @return the exit status of the process
*/
int exitStatus() const;
/**
* Transmit data to the child process's stdin.
*
* KProcess::writeStdin may return false in the following cases:
*
* @li The process is not currently running.
*
* @li Communication to stdin has not been requested in the @ref start() call.
*
* @li Transmission of data to the child process by a previous call to
* @ref writeStdin() is still in progress.
*
* Please note that the data is sent to the client asynchronously,
* so when this function returns, the data might not have been
* processed by the child process.
*
* If all the data has been sent to the client, the signal
* @ref wroteStdin() will be emitted.
*
* Please note that you must not free "buffer" or call @ref writeStdin()
* again until either a @ref wroteStdin() signal indicates that the
* data has been sent or a @ref processHasExited() signal shows that
* the child process is no longer alive...
* @param buffer the buffer to write. Do not free or modify it until
* you got a @ref wroteStdin() or @ref processHasExited() signal
* @return false if an error has occurred
**/
bool writeStdin(const char *buffer, int buflen);
/**
* This causes the stdin file descriptor of the child process to be
* closed indicating an "EOF" to the child.
*
* @return false if no communication to the process's stdin
* had been specified in the call to @ref start().
*/
bool closeStdin();
/**
* This causes the stdout file descriptor of the child process to be
* closed.
*
* @return false if no communication to the process's stdout
* had been specified in the call to @ref start().
*/
bool closeStdout();
/**
* This causes the stderr file descriptor of the child process to be
* closed.
*
* @return false if no communication to the process's stderr
* had been specified in the call to @ref start().
*/
bool closeStderr();
/**
* Lets you see what your arguments are for debugging.
* @return the list of arguments
*/
const QValueList &args() { return arguments; }
/**
* Controls whether the started process should drop any
* setuid/segid privileges or whether it should keep them
*
* The default is false : drop privileges
* @param true to keep the privileges
*/
void setRunPrivileged(bool keepPrivileges);
/**
* Returns whether the started process will drop any
* setuid/segid privileges or whether it will keep them
* @return true if the process runs privileged
*/
bool runPrivileged() const;
/**
* Modifies the environment of the process to be started.
* This function must be called before starting the process.
* @param name the name of the environment variable
* @param value the new value for the environment variable
*/
void setEnvironment(const QString &name, const QString &value);
/**
* Changes the current working directory (CWD) of the process
* to be started.
* This function must be called before starting the process.
* @param dir the new directory
*/
void setWorkingDirectory(const QString &dir);
/**
* Specify whether to start the command via a shell or directly.
* The default is to start the command directly.
* If @p useShell is true @p shell will be used as shell, or
* if shell is empty, the standard shell is used.
* @p quote A flag indicating whether to quote the arguments.
*
* When using a shell, the caller should make sure that all filenames etc.
* are properly quoted when passed as argument.
* @see quote()
* @param useShell true if the command should be started via a shell
* @param shell the path to the shell that will execute the process, or
* 0 to use the standard shell
* @since 3.1
*/
void setUseShell(bool useShell, const char *shell = 0);
/**
* This function can be used to quote an argument string such that
* the shell processes it properly. This is e. g. necessary for
* user-provided file names which may contain spaces or quotes.
* It also prevents expansion of wild cards and environment variables.
* @param arg the argument to quite
* @return the quoted argument
* @since 3.1
*/
static QString quote(const QString &arg);
/**
* Detaches KProcess from child process. All communication is closed.
* No exit notification is emitted any more for the child process.
* Deleting the KProcess will no longer kill the child process.
* Note that the current process remains the parent process of the
* child process.
*/
void detach();
signals:
/**
* Emitted after the process has terminated when
* the process was run in the @p NotifyOnExit (==default option to
* @ref start()) or the @ref Block mode.
* @param proc a pointer to the process that has exited
**/
void processExited(KProcess *proc);
/**
* Emitted, when output from the child process has
* been received on stdout.
*
* To actually get
* these signals, the respective communication link (stdout/stderr)
* has to be turned on in @ref start().
*
* @param proc a pointer to the process that has received the output
* @param buffer The data received.
* @param buflen The number of bytes that are available.
*
* You should copy the information contained in @p buffer to your private
* data structures before returning from this slot.
* Example:
* QString myBuf = QString::fromLatin1(buffer, buflen);
**/
void receivedStdout(KProcess *proc, char *buffer, int buflen);
/**
* Emitted when output from the child process has
* been received on stdout.
*
* To actually get these signals, the respective communications link
* (stdout/stderr) has to be turned on in @ref start() and the
* @p NoRead flag should have been passed.
*
* You will need to explicitly call resume() after your call to start()
* to begin processing data from the child process's stdout. This is
* to ensure that this signal is not emitted when no one is connected
* to it, otherwise this signal will not be emitted.
*
* The data still has to be read from file descriptor @p fd.
* @param fd the file descriptor that provides the data
* @param len the number of bytes that have been read from fd must be written here
**/
void receivedStdout(int fd, int &len);
/**
* Emitted, when output from the child process has
* been received on stderr.
* To actually get
* these signals, the respective communication link (stdout/stderr)
* has to be turned on in @ref start().
*
* You should copy the information contained in @p buffer to your private
* data structures before returning from this slot.
*
* @param proc a pointer to the process that has received the data
* @param buffer The data received.
* @param buflen The number of bytes that are available.
*/
void receivedStderr(KProcess *proc, char *buffer, int buflen);
/**
* Emitted after all the data that has been
* specified by a prior call to @ref writeStdin() has actually been
* written to the child process.
* @param proc a pointer to the process
**/
void wroteStdin(KProcess *proc);
protected slots:
/**
* This slot gets activated when data from the child's stdout arrives.
* It usually calls "childOutput"
* @param the file descriptor for the output
*/
void slotChildOutput(int fdno);
/**
* This slot gets activated when data from the child's stderr arrives.
* It usually calls "childError"
* @param the file descriptor for the output
*/
void slotChildError(int fdno);
/*
Slot functions for capturing stdout and stderr of the child
*/
/**
* Called when another bulk of data can be sent to the child's
* stdin. If there is no more data to be sent to stdin currently
* available, this function must disable the QSocketNotifier "innot".
* @param dummy ignore this argument
*/
void slotSendData(int dummy);
protected:
/**
* Sets up the environment according to the data passed via
* setEnvironment(...)
*/
void setupEnvironment();
/**
* The list of the process' command line arguments. The first entry
* in this list is the executable itself.
*/
QValueList arguments;
/**
* How to run the process (Block, NotifyOnExit, DontCare). You should
* not modify this data member directly from derived classes.
*/
RunMode run_mode;
/**
* true if the process is currently running. You should not
* modify this data member directly from derived classes. For
* reading the value of this data member, please use "isRunning()"
* since "runs" will probably be made private in later versions
* of KProcess.
*/
bool runs;
/**
* The PID of the currently running process (see "getPid()").
* You should not modify this data member in derived classes.
* Please use "getPid()" instead of directly accessing this
* member function since it will probably be made private in
* later versions of KProcess.
*/
pid_t pid_;
/**
* The process' exit status as returned by "waitpid". You should not
* modify the value of this data member from derived classes. You should
* rather use @ref exitStatus than accessing this data member directly
* since it will probably be made private in further versions of
* KProcess.
*/
int status;
/**
* See setRunPrivileged()
*/
bool keepPrivs;
/*
Functions for setting up the sockets for communication.
setupCommunication
-- is called from "start" before "fork"ing.
commSetupDoneP
-- completes communication socket setup in the parent
commSetupDoneC
-- completes communication setup in the child process
commClose
-- frees all allocated communication resources in the parent
after the process has exited
*/
/**
* This function is called from "KProcess::start" right before a "fork" takes
* place. According to
* the "comm" parameter this function has to initialize the "in", "out" and
* "err" data member of KProcess.
*
* This function should return 0 if setting the needed communication channels
* was successful.
*
* The default implementation is to create UNIX STREAM sockets for the communication,
* but you could overload this function and establish a TCP/IP communication for
* network communication, for example.
*/
virtual int setupCommunication(Communication comm);
/**
* Called right after a (successful) fork on the parent side. This function
* will usually do some communications cleanup, like closing the reading end
* of the "stdin" communication channel.
*
* Furthermore, it must also create the QSocketNotifiers "innot", "outnot" and
* "errnot" and connect their Qt slots to the respective KProcess member functions.
*
* For a more detailed explanation, it is best to have a look at the default
* implementation of "setupCommunication" in kprocess.cpp.
*/
virtual int commSetupDoneP();
/**
* Called right after a (successful) fork, but before an "exec" on the child
* process' side. It usually just closes the unused communication ends of
* "in", "out" and "err" (like the writing end of the "in" communication
* channel.
*/
virtual int commSetupDoneC();
/**
* Immediately called after a process has exited. This function normally
* calls commClose to close all open communication channels to this
* process and emits the "processExited" signal (if the process was
* not running in the "DontCare" mode).
*/
virtual void processHasExited(int state);
/**
* Should clean up the communication links to the child after it has
* exited. Should be called from "processHasExited".
*/
virtual void commClose();
/**
* the socket descriptors for stdin/stdout/stderr.
*/
int out[2];
int in[2];
int err[2];
/**
* The socket notifiers for the above socket descriptors.
*/
QSocketNotifier *innot;
QSocketNotifier *outnot;
QSocketNotifier *errnot;
/**
* Lists the communication links that are activated for the child
* process. Should not be modified from derived classes.
*/
Communication communication;
/**
* Called by "slotChildOutput" this function copies data arriving from the
* child process's stdout to the respective buffer and emits the signal
* "@ref receivedStderr".
*/
int childOutput(int fdno);
/**
* Called by "slotChildOutput" this function copies data arriving from the
* child process's stdout to the respective buffer and emits the signal
* "@ref receivedStderr"
*/
int childError(int fdno);
// information about the data that has to be sent to the child:
const char *input_data; // the buffer holding the data
int input_sent; // # of bytes already transmitted
int input_total; // total length of input_data
/**
* @ref KProcessController is a friend of KProcess because it has to have
* access to various data members.
*/
friend class KProcessController;
private:
/**
* Searches for a valid shell.
* Here is the algorithm used for finding an executable shell:
*
* @li Try the executable pointed to by the "SHELL" environment
* variable with white spaces stripped off
*
* @li If your process runs with uid != euid or gid != egid, a shell
* not listed in /etc/shells will not used.
*
* @li If no valid shell could be found, "/bin/sh" is used as a last resort.
* @since 3.1
*/
QCString searchShell();
/**
* Used by @ref searchShell in order to find out whether the shell found
* is actually executable at all.
* @since 3.1
*/
bool isExecutable(const QCString &filename);
// Disallow assignment and copy-construction
KProcess( const KProcess& );
KProcess& operator= ( const KProcess& );
protected:
virtual void virtual_hook( int id, void* data );
private:
KProcessPrivate *d;
};
class KShellProcessPrivate;
/**
* @obsolete
*
* This class is obsolete. Use KProcess and KProcess::setUseShell(true)
* instead.
*
* @short A class derived from @ref KProcess to start child
* processes through a shell.
* @author Christian Czezakte
* @version $Id: kprocess_h.html 203394 2003-01-28 18:16:22Z ctennis $
*/
class KShellProcess: public KProcess
{
Q_OBJECT
public:
/**
* Constructor
*
* By specifying the name of a shell (like "/bin/bash") you can override
* the mechanism for finding a valid shell as described in KProcess::searchShell()
*/
KShellProcess(const char *shellname=0);
/**
* Destructor.
*/
~KShellProcess();
/**
* Starts up the process. -- For a detailed description
* have a look at the "start" member function and the detailed
* description of @ref KProcess .
*/
virtual bool start(RunMode runmode = NotifyOnExit,
Communication comm = NoCommunication);
/**
* This function can be used to quote an argument string such that
* the shell processes it properly. This is e. g. necessary for
* user-provided file names which may contain spaces or quotes.
* It also prevents expansion of wild cards and environment variables.
*/
static QString quote(const QString &arg);
private:
QCString shell;
// Disallow assignment and copy-construction
KShellProcess( const KShellProcess& );
KShellProcess& operator= ( const KShellProcess& );
protected:
virtual void virtual_hook( int id, void* data );
private:
KShellProcessPrivate *d;
};
#endif
| Generated by: caleb on tcdevel on Tue Jan 28 12:54:04 2003, using kdoc $. |