summaryrefslogtreecommitdiffabout
path: root/microkde/oprocess.h
Side-by-side diff
Diffstat (limited to 'microkde/oprocess.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/oprocess.h761
1 files changed, 0 insertions, 761 deletions
diff --git a/microkde/oprocess.h b/microkde/oprocess.h
deleted file mode 100644
index be1436c..0000000
--- a/microkde/oprocess.h
+++ b/dev/null
@@ -1,761 +0,0 @@
-/*
-                This file is part of the Opie Project
-             Copyright (C) 2003-2004 Holger Freyther <zecke@handhelds.org>
- Copyright (C) The Opie Team <opie-devel@handhelds.org>
- =. Based on KProcess (C) 1997 Christian Czezatke (e9025461@student.tuwien.ac.at)
- .=l.
-          .>+-=
-_;:,     .>    :=|. This program is free software; you can
-.> <`_,   >  .   <= redistribute it and/or modify it under
-:`=1 )Y*s>-.--   : the terms of the GNU Library General Public
-.="- .-=="i,     .._ License as published by the Free Software
-- .   .-<_>     .<> Foundation; either version 2 of the License,
-    ._= =}       : or (at your option) any later version.
-   .%`+i>       _;_.
-   .i_,=:_.      -<s. This program 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.
-*/
-
-#ifndef OPROCESS_H
-#define OPROCESS_H
-
-/* QT */
-#include <qcstring.h>
-#include <qobject.h>
-#include <qvaluelist.h>
-
-/* STD */
-#include <sys/types.h> // for pid_t
-#include <sys/wait.h>
-#include <signal.h>
-#include <unistd.h>
-
-class QSocketNotifier;
-
-namespace Opie {
-namespace Core {
-namespace Internal {
-class OProcessController;
-class OProcessPrivate;
-}
-
-/**
- * Child process invocation, monitoring and control.
- *
- * @sect General usage and features
- *
- *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(Opie::Core::OProcess *)),
- * pointer_to_my_object, SLOT(my_objects_slot(Opie::Core::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
- *@author Holger Freyther (Opie Port)
- *
- **/
-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 );
-
- /**
- * 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;
-
- /**
- * 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 );
-
- 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.
- * \todo make const
- */
-
- 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();
-
- /**
- * @return the PID of @a process, or -1 if the process is not running
- */
- static int processPID( const QString& process );
-
-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( Opie::Core::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( Opie::Core::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( Opie::Core::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( Opie::Core::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 Internal::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& );
-
-private:
- void init ( );
- Internal::OProcessPrivate *d;
-};
-}
-}
-
-#endif
-