1 | /* |
2 | This file is part of the KDE libraries |
3 | SPDX-FileCopyrightText: 2007 Oswald Buddenhagen <ossi@kde.org> |
4 | |
5 | SPDX-License-Identifier: LGPL-2.0-or-later |
6 | */ |
7 | |
8 | #ifndef KPTYPROCESS_H |
9 | #define KPTYPROCESS_H |
10 | |
11 | #include <KProcess> |
12 | |
13 | #include "kpty_export.h" |
14 | |
15 | #include <memory> |
16 | |
17 | class KPtyDevice; |
18 | |
19 | class KPtyProcessPrivate; |
20 | |
21 | /*! |
22 | * \class KPtyProcess |
23 | * \inmodule KPty |
24 | * |
25 | * \brief This class extends KProcess by support for PTYs (pseudo TTYs). |
26 | * |
27 | * The PTY is opened as soon as the class is instantiated. Verify that |
28 | * it was opened successfully by checking that pty()->masterFd() is not -1. |
29 | * |
30 | * The PTY is always made the process' controlling TTY. |
31 | * Utmp registration and connecting the stdio handles to the PTY are optional. |
32 | * |
33 | * No attempt to integrate with QProcess' waitFor*() functions was made, |
34 | * for it is impossible. Note that execute() does not work with the PTY, too. |
35 | * Use the PTY device's waitFor*() functions or use it asynchronously. |
36 | * |
37 | * \note If you inherit from this class and use setChildProcessModifier() in |
38 | * the derived class, you must call the childProcessModifier() of KPtyProcess |
39 | * first (using setChildProcessModifier() in the derived class will "overwrite" |
40 | * the childProcessModifier() std::function that was previously set by KPtyProcess). |
41 | * |
42 | * For example: |
43 | * \code |
44 | * class MyProcess : public KPtyProcess |
45 | * { |
46 | * MyProcess() |
47 | * { |
48 | * auto parentChildProcModifier = KPtyProcess::childProcessModifier(); |
49 | * setChildProcessModifier([parentChildProcModifier]() { |
50 | * // First call the parent class modifier function |
51 | * if (parentChildProcModifier) { |
52 | * parentChildProcModifier(); |
53 | * } |
54 | * // Then whatever extra code you need to run |
55 | * .... |
56 | * .... |
57 | * }); |
58 | * } |
59 | * \endcode |
60 | */ |
61 | class KPTY_EXPORT KPtyProcess : public KProcess |
62 | { |
63 | Q_OBJECT |
64 | Q_DECLARE_PRIVATE(KPtyProcess) |
65 | |
66 | public: |
67 | /*! |
68 | * \value NoChannels The PTY is not connected to any channel |
69 | * \value StdinChannel Connect PTY to stdin |
70 | * \value StdoutChannel Connect PTY to stdout |
71 | * \value StderrChannel Connect PTY to stderr |
72 | * \value AllOutputChannels Connect PTY to all output channels |
73 | * \value AllChannels Connect PTY to all channels |
74 | */ |
75 | enum PtyChannelFlag { |
76 | NoChannels = 0, |
77 | StdinChannel = 1, |
78 | StdoutChannel = 2, |
79 | StderrChannel = 4, |
80 | AllOutputChannels = 6, |
81 | AllChannels = 7, |
82 | }; |
83 | Q_DECLARE_FLAGS(PtyChannels, PtyChannelFlag) |
84 | |
85 | /*! |
86 | * Constructor |
87 | */ |
88 | explicit KPtyProcess(QObject *parent = nullptr); |
89 | |
90 | /*! |
91 | * Construct a process using an open pty master. |
92 | * |
93 | * \a ptyMasterFd an open pty master file descriptor. |
94 | * The process does not take ownership of the descriptor; |
95 | * it will not be automatically closed at any point. |
96 | */ |
97 | KPtyProcess(int ptyMasterFd, QObject *parent = nullptr); |
98 | |
99 | ~KPtyProcess() override; |
100 | |
101 | /*! |
102 | * Set to which channels the PTY should be assigned. |
103 | * |
104 | * This function must be called before starting the process. |
105 | * |
106 | * \a channels the output channel handling mode |
107 | */ |
108 | void setPtyChannels(PtyChannels channels); |
109 | |
110 | /*! |
111 | * Query to which channels the PTY is assigned. |
112 | * |
113 | * Returns the output channel handling mode |
114 | */ |
115 | PtyChannels ptyChannels() const; |
116 | |
117 | /*! |
118 | * Set whether to register the process as a TTY login in utmp. |
119 | * |
120 | * Utmp is disabled by default. |
121 | * It should enabled for interactively fed processes, like terminal |
122 | * emulations. |
123 | * |
124 | * This function must be called before starting the process. |
125 | * |
126 | * \a value whether to register in utmp. |
127 | */ |
128 | void setUseUtmp(bool value); |
129 | |
130 | /*! |
131 | * Get whether to register the process as a TTY login in utmp. |
132 | * |
133 | * Returns whether to register in utmp |
134 | */ |
135 | bool isUseUtmp() const; |
136 | |
137 | /*! |
138 | * Get the PTY device of this process. |
139 | * |
140 | * Returns the PTY device |
141 | */ |
142 | KPtyDevice *pty() const; |
143 | |
144 | private: |
145 | std::unique_ptr<KPtyProcessPrivate> const d_ptr; |
146 | }; |
147 | |
148 | Q_DECLARE_OPERATORS_FOR_FLAGS(KPtyProcess::PtyChannels) |
149 | |
150 | #endif |
151 | |