kdesu/process.h

   1 ///////// XXX migrate it to kprocess /////////////////
   2
   3 /* vi: ts=8 sts=4 sw=4
   4  *
   5  * This file is part of the KDE project, module kdesu.
   6  * Copyright (C) 1999,2000 Geert Jansen <jansen@kde.org>
   7  *
   8  * This is free software; you can use this library under the GNU Library
   9  * General Public License, version 2. See the file "COPYING.LIB" for the
  10  * exact licensing terms.
  11  */
  12
  13 #ifndef __Process_h_Included__
  14 #define __Process_h_Included__
  15
  16 #include <sys/types.h>
  17
  18 #include <QtCore/QByteRef>
  19 #include <QtCore/QString>
  20 #include <QtCore/QStringList>
  21 #include <QtCore/QList>
  22
  23 #include <kdesu/kdesu_export.h>
  24
  25 #include <kpty.h>
  26
  27 namespace KDESu {
  28
  29 /** \class PtyProcess process.h kdesu/process.h
  30  * Synchronous communication with tty programs.
  31  *
  32  * PtyProcess provides synchronous communication with tty based programs.
  33  * The communications channel used is a pseudo tty (as opposed to a pipe)
  34  * This means that programs which require a terminal will work.
  35  */
  36
  37 class KDESU_EXPORT PtyProcess
  38 {
  39 public:
  40     PtyProcess();
  41     virtual ~PtyProcess();
  42
  43     /**
  44      * Forks off and execute a command. The command's standard in and output
  45      * are connected to the pseudo tty. They are accessible with readLine
  46      * and writeLine.
  47      * @param command The command to execute.
  48      * @param args The arguments to the command.
  49      * @return 0 on success, -1 on error. errno might give more information then.
  50      */
  51     int exec(const QByteArray &command, const QList<QByteArray> &args);
  52
  53     /**
  54      * Reads a line from the program's standard out. Depending on the @em block
  55      * parameter, this call blocks until something was read.
  56      * Note that in some situations this function will return less than a full
  57      * line of output, but never more. Newline characters are stripped.
  58      * @param block Block until a full line is read?
  59      * @return The output string.
  60      */
  61     QByteArray readLine(bool block=true);
  62
  63     /**
  64      * Read all available output from the program's standard out.
  65      * @param block If no output is in the buffer, should the function block
  66      * (else it will return an empty QByteArray)?
  67      * @return The output.
  68      */
  69     QByteArray readAll(bool block=true);
  70
  71     /**
  72      * Writes a line of text to the program's standard in.
  73      * @param line The text to write.
  74      * @param addNewline Adds a '\n' to the line.
  75      */
  76     void writeLine(const QByteArray &line, bool addNewline=true);
  77
  78     /**
  79      * Puts back a line of input.
  80      * @param line The line to put back.
  81      * @param addNewline Adds a '\n' to the line.
  82      */
  83     void unreadLine(const QByteArray &line, bool addNewline=true);
  84
  85     /**
  86      * Sets the exit string. If a line of program output matches this,
  87      * waitForChild() will terminate the program and return.
  88      */
  89     void setExitString(const QByteArray &exit);
  90
  91     /**
  92      * Waits for the child to exit. See also setExitString.
  93      */
  94     int waitForChild();
  95
  96     /**
  97      * Waits until the pty has cleared the ECHO flag. This is useful
  98      * when programs write a password prompt before they disable ECHO.
  99      * Disabling it might flush any input that was written.
 100      */
 101     int WaitSlave();
 102
 103     /**
 104      * Enables/disables local echo on the pseudo tty.
 105      */
 106     int enableLocalEcho(bool enable=true);
 107
 108     /**
 109      * Enables/disables terminal output. Relevant only to some subclasses.
 110      */
 111     void setTerminal(bool terminal);
 112
 113     /**
 114      * Overwrites the password as soon as it is used. Relevant only to
 115      * some subclasses.
 116      */
 117     void setErase(bool erase);
 118
 119     /**
 120      * Set additinal environment variables.
 121      */
 122     void setEnvironment( const QList<QByteArray> &env );
 123
 124     /**
 125      * Returns the filedescriptor of the process.
 126      */
 127     int fd() const;
 128
 129     /**
 130      * Returns the pid of the process.
 131      */
 132     int pid() const;
 133
 134 public /* static */:
 135     /*
 136     ** This is a collection of static functions that can be
 137     ** used for process control inside kdesu. I'd suggest
 138     ** against using this publicly. There are probably
 139     ** nicer Qt based ways to do what you want.
 140     */
 141
 142     /**
 143     ** Wait @p ms miliseconds (ie. 1/10th of a second is 100ms),
 144     ** using @p fd as a filedescriptor to wait on. Returns
 145     ** select(2)'s result, which is -1 on error, 0 on timeout,
 146     ** or positive if there is data on one of the selected fd's.
 147     **
 148     ** @p ms must be in the range 0..999 (i.e. the maximum wait
 149     ** duration is 999ms, almost one second).
 150     */
 151     static int waitMS(int fd,int ms);
 152
 153
 154     /**
 155     ** Basic check for the existence of @p pid.
 156     ** Returns true iff @p pid is an extant process,
 157     ** (one you could kill - see man kill(2) for signal 0).
 158     */
 159     static bool checkPid(pid_t pid);
 160
 161
 162     /** Error return values for checkPidExited() */
 163     enum checkPidStatus { Error=-1,  /**< No child */
 164         NotExited=-2,                /**< Child hasn't exited */
 165         Killed=-3                    /**< Child terminated by signal */
 166     } ;
 167
 168     /**
 169     ** Check process exit status for process @p pid.
 170     ** If child @p pid has exited, return its exit status,
 171     ** (which may be zero).
 172     ** On error (no child, no exit), return -1.
 173     ** If child @p has not exited, return -2.
 174     */
 175     static int checkPidExited(pid_t pid);
 176
 177
 178 protected:
 179     QList<QByteArray> environment() const;
 180
 181     bool m_bErase,   /**< @see setErase() */
 182         m_bTerminal; /**< Indicates running in a terminal, causes additional
 183                           newlines to be printed after output. Set to @c false
 184                           in constructor. @see setTerminal()  */
 185     int m_Pid; /**< PID of child process */
 186     QByteArray m_Command,  /**< Unused */
 187         m_Exit;            /**< String to scan for in output that indicates
 188                                 child has exited. */
 189
 190 private:
 191     int init();
 192     int setupTTY();
 193
 194 protected:
 195     /** Standard hack to add virtual methods in a BC way. Unused. */
 196     virtual void virtual_hook( int id, void* data );
 197 private:
 198     class PtyProcessPrivate;
 199     PtyProcessPrivate* const d;
 200 };
 201
 202 }
 203
 204 #endif