| -rw-r--r-- | libopie/oprocess.h | 805 |
1 files changed, 805 insertions, 0 deletions
diff --git a/libopie/oprocess.h b/libopie/oprocess.h new file mode 100644 index 0000000..ce3c87d --- a/dev/null +++ b/libopie/oprocess.h @@ -0,0 +1,805 @@ +/* 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 +// Ported by Holger Freyther +// + +#ifndef __kprocess_h__ +#define __kprocess_h__ + +#include <sys/types.h> // for pid_t +#include <sys/wait.h> +#include <signal.h> +#include <unistd.h> +#include <qvaluelist.h> +#include <qcstring.h> +#include <qobject.h> + +class QSocketNotifier; +class OProcessPrivate; + +/** + * 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 OProcess::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 OProcess::NotifyOnExit -- The child process is invoked and both the + *child and the parent process run concurrently. + * + *When the child process exits, the OProcess 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 OProcess objects gets destructed, the child + *process will be killed if it is still running! + *This means in particular, that you cannot use a OProcess on the stack + *with OProcess::NotifyOnExit. + * + *@li OProcess::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.) + * + *OProcess 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: + *<pre> + *OProcess *proc = new OProcess; + * + **proc << "my_executable"; + **proc << "These" << "are" << "the" << "command" << "line" << "args"; + *QApplication::connect(proc, SIGNAL(processExited(OProcess *)), + * pointer_to_my_object, SLOT(my_objects_slot(OProcess *))); + *proc->start(); + *</pre> + * + *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 + * + *OProcess 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(OProcess *proc, char *buffer, int buflen); + *@li void @ref receivedStderr(OProcess *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(OProcess *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 OProcess : 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 | @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 + */ + OProcess(); + + /** + *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 ~OProcess(); + + /** + @deprecated + + The use of this function is now deprecated. -- Please use the + "operator<<" instead of "setExecutable". + + Sets the executable to be started with this OProcess 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: + * <pre> + * OProcess p; + * ... + * p << "ls" << "-l" << "/usr/local/bin" + * </pre> + * + **/ + OProcess &operator<<(const QString& arg); + /** + * Similar to previous method, takes a char *, supposed to be in locale 8 bit already. + */ + OProcess &operator<<(const char * arg); + /** + * Similar to previous method, takes a QCString, supposed to be in locale 8 bit already. + */ + OProcess &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. + **/ + OProcess &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 OProcess 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 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 @p true if the signal was delivered successfully. + */ + virtual bool kill(int signo = SIGTERM); + + /** + @return @p 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 OProcess. + * + * Calling it before any child process has been started by this + * OProcess instance causes pid() to return 0. + **/ + 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 @p 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 OProcess::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 OProcess::normalExit() to check whether the process has exited + * cleanly (i.e., @ref OProcess::normalExit() returns @p true) before calling + * this function because if the process did not exit normally, + * it does not have a valid exit status. + */ + int exitStatus() const; + + + /** + * Transmit data to the child process's stdin. + * + * OProcess::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... + **/ + 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 @p 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 @p 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 @p 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. + */ + + const QValueList<QCString> &args() { return arguments; } + + /** + * Controls whether the started process should drop any + * setuid/segid privileges or whether it should keep them + * + * The default is @p false : drop privileges + */ + void setRunPrivileged(bool keepPrivileges); + + /** + * Returns whether the started process will drop any + * setuid/segid privileges or whether it will keep them + */ + bool runPrivileged() const; + + /** + * Modifies the environment of the process to be started. + * This function must be called before starting the process. + */ + 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. + */ + 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() + */ + 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. + */ + static QString quote(const QString &arg); + + /** + * Detaches OProcess from child process. All communication is closed. + * No exit notification is emitted any more for the child process. + * Deleting the OProcess 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. + **/ + void processExited(OProcess *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 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. + **/ + void receivedStdout(OProcess *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. + **/ + 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(). + * + * @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. + */ + void receivedStderr(OProcess *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. + **/ + void wroteStdin(OProcess *proc); + + +protected slots: + + /** + * This slot gets activated when data from the child's stdout arrives. + * It usually calls "childOutput" + */ + void slotChildOutput(int fdno); + + /** + * This slot gets activated when data from the child's stderr arrives. + * It usually calls "childError" + */ + 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". + */ + 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<QCString> 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 OProcess. + */ + 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 OProcess. + */ + 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 + * OProcess. + */ + 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 "OProcess::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 OProcess. + * + * 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 OProcess 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 OProcessController is a friend of OProcess because it has to have + * access to various data members. + */ + friend class OProcessController; + + +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. + */ + QCString searchShell(); + + /** + * Used by @ref searchShell in order to find out whether the shell found + * is actually executable at all. + */ + bool isExecutable(const QCString &filename); + + // Disallow assignment and copy-construction + OProcess( const OProcess& ); + OProcess& operator= ( const OProcess& ); + +protected: + virtual void virtual_hook( int id, void* data ); +private: + OProcessPrivate *d; +}; + +class KShellProcessPrivate; + +/** +* @obsolete +* +* This class is obsolete. Use OProcess and OProcess::setUseShell(true) +* instead. +* +* @short A class derived from @ref OProcess to start child +* processes through a shell. +* @author Christian Czezakte <e9025461@student.tuwien.ac.at> +* @version $Id$ +*/ +class KShellProcess: public OProcess +{ + 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 OProcess::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 OProcess . + */ + 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 + |