| -rw-r--r-- | libopie/oprocess.h | 24 |
1 files changed, 15 insertions, 9 deletions
diff --git a/libopie/oprocess.h b/libopie/oprocess.h index bf5fe0e..f2853b0 100644 --- a/libopie/oprocess.h +++ b/libopie/oprocess.h @@ -1,97 +1,97 @@ /* 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 to the Open Palmtop Integrated Environment // #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 + *This class allows a KDE and OPIE 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> @@ -143,97 +143,103 @@ class OProcessPrivate; *@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(QObject *parent = 0, const char *name = 0); + /** + * Constructor + */ OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0); + /** + * Constructor + */ OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0); /** *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); @@ -365,237 +371,237 @@ public: void flushStdin(); /** * 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 + * 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(); + 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 + * 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 + * 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; /* @@ -667,81 +673,81 @@ protected: * 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. + * 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& ); private: void init ( ); OProcessPrivate *d; }; #endif |