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
27namespace 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
37class KDESU_EXPORT PtyProcess
38{
39public:
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
134public /* 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
178protected:
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
190private:
191 int init();
192 int setupTTY();
193
194protected:
195 /** Standard hack to add virtual methods in a BC way. Unused. */
196 virtual void virtual_hook( int id, void* data );
197private:
198 class PtyProcessPrivate;
199 PtyProcessPrivate* const d;
200};
201
202}
203
204#endif
205