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
17class KPtyDevice;
18
19class KPtyProcessPrivate;
20
21/**
22 * This class extends KProcess by support for PTYs (pseudo TTYs).
23 *
24 * The PTY is opened as soon as the class is instantiated. Verify that
25 * it was opened successfully by checking that pty()->masterFd() is not -1.
26 *
27 * The PTY is always made the process' controlling TTY.
28 * Utmp registration and connecting the stdio handles to the PTY are optional.
29 *
30 * No attempt to integrate with QProcess' waitFor*() functions was made,
31 * for it is impossible. Note that execute() does not work with the PTY, too.
32 * Use the PTY device's waitFor*() functions or use it asynchronously.
33 *
34 * @note If you inherit from this class and use setChildProcessModifier() in
35 * the derived class, you must call the childProcessModifier() of KPtyProcess
36 * first (using setChildProcessModifier() in the derived class will "overwrite"
37 * the childProcessModifier() std::function that was previously set by KPtyProcess).
38 * For example:
39 * @code
40 * class MyProcess : public KPtyProcess
41 * {
42 * MyProcess()
43 * {
44 * auto parentChildProcModifier = KPtyProcess::childProcessModifier();
45 * setChildProcessModifier([parentChildProcModifier]() {
46 * // First call the parent class modifier function
47 * if (parentChildProcModifier) {
48 * parentChildProcModifier();
49 * }
50 * // Then whatever extra code you need to run
51 * ....
52 * ....
53 * });
54 * }
55 * @endcode
56 *
57 * @author Oswald Buddenhagen <ossi@kde.org>
58 */
59class KPTY_EXPORT KPtyProcess : public KProcess
60{
61 Q_OBJECT
62 Q_DECLARE_PRIVATE(KPtyProcess)
63
64public:
65 /**
66 * @see PtyChannels
67 */
68 enum PtyChannelFlag {
69 NoChannels = 0, /**< The PTY is not connected to any channel. */
70 StdinChannel = 1, /**< Connect PTY to stdin. */
71 StdoutChannel = 2, /**< Connect PTY to stdout. */
72 StderrChannel = 4, /**< Connect PTY to stderr. */
73 AllOutputChannels = 6, /**< Connect PTY to all output channels. */
74 AllChannels = 7, /**< Connect PTY to all channels. */
75 };
76
77 /**
78 * Stores a combination of #PtyChannelFlag values.
79 */
80 Q_DECLARE_FLAGS(PtyChannels, PtyChannelFlag)
81
82 /**
83 * Constructor
84 */
85 explicit KPtyProcess(QObject *parent = nullptr);
86
87 /**
88 * Construct a process using an open pty master.
89 *
90 * @param ptyMasterFd an open pty master file descriptor.
91 * The process does not take ownership of the descriptor;
92 * it will not be automatically closed at any point.
93 */
94 KPtyProcess(int ptyMasterFd, QObject *parent = nullptr);
95
96 /**
97 * Destructor
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 * @param 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 * @return 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 * @param 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 * @return whether to register in utmp
134 */
135 bool isUseUtmp() const;
136
137 /**
138 * Get the PTY device of this process.
139 *
140 * @return the PTY device
141 */
142 KPtyDevice *pty() const;
143
144private:
145 std::unique_ptr<KPtyProcessPrivate> const d_ptr;
146};
147
148Q_DECLARE_OPERATORS_FOR_FLAGS(KPtyProcess::PtyChannels)
149
150#endif
151

source code of kpty/src/kptyprocess.h