Класс QProcess

Класс QProcess используется для запуска внешних программ и для общения с ними. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Примечание: Все функции в этом классе являются перевходными.

Типы общего доступа

Функции общего доступа

Реализованные функции общего доступа

• 43 public functions inherited from QIODevice
• 32 public functions inherited from QObject

Public Slots

• 1 public slot inherited from QObject

Сигналы

• 6 signals inherited from QIODevice
• 2 signals inherited from QObject

Статические публичные члены

• 11 static public members inherited from QObject

Защищенные функции

Переопределённые защищённые функции

• 5 protected functions inherited from QIODevice
• 9 protected functions inherited from QObject

Связанные нечлены

Макросы

Дополнительные унаследованные члены

• 1 property inherited from QObject

Подробное описание

Класс QProcess используется для запуска внешних программ и взаимодействия с ними.

Запуск процесса

Чтобы запустить процесс, передайте имя и аргументы командной строки программы, которую вы хотите запустить, в качестве аргументов функции start(). Аргументы предоставляются как отдельные строки в QStringList.

В качестве альтернативы можно задать программу для запуска с помощью setProgram() и setArguments(), а затем вызвать start() или open().

Например, следующий фрагмент кода запускает пример аналоговых часов в стиле Fusion на платформах X11, передавая строки, содержащие "-style" и "fusion", в качестве двух элементов в списке аргументов:

    QObject *parent;
    ...
    QString program = "./path/to/Qt/examples/widgets/analogclock";
    QStringList arguments;
    arguments << "-style" << "fusion";

    QProcess *myProcess = new QProcess(parent);
    myProcess->start(program, arguments);

Затем QProcess переходит в состояние Starting, и когда программа запущена, QProcess переходит в состояние Running и излучает started().

QProcess позволяет обрабатывать процесс как последовательное устройство ввода-вывода. Вы можете записывать в него и читать из него так же, как вы бы работали с сетевым соединением, используя QTcpSocket. Затем вы можете записать в стандартный ввод процесса, вызвав write(), и прочитать стандартный вывод, вызвав read(), readLine() и getChar(). Поскольку он наследуется от QIODevice, QProcess также можно использовать в качестве источника ввода для QXmlReader или для генерации данных для загрузки с помощью QNetworkAccessManager.

Когда процесс завершается, QProcess возвращается в состояние NotRunning (начальное состояние) и излучает finished().

Сигнал finished() предоставляет код завершения и статус завершения процесса в качестве аргументов, и вы также можете вызвать exitCode(), чтобы получить код завершения последнего завершённого процесса, и exitStatus(), чтобы получить его статус завершения. Если в какой-либо момент времени произойдёт ошибка, QProcess излучит сигнал errorOccurred(). Вы также можете вызвать error(), чтобы найти тип произошедшей последней ошибки, и state(), чтобы найти текущее состояние процесса.

Примечание: QProcess не поддерживается на VxWorks, iOS, tvOS, watchOS или Universal Windows Platform.

Взаимодействие через каналы

Процессы имеют два предопределённых канала вывода: канал стандартного вывода (stdout) предоставляет обычный вывод консоли, а канал стандартной ошибки (stderr) обычно предоставляет ошибки, которые выводит процесс. Эти каналы представляют два отдельных потока данных. Вы можете переключаться между ними, вызывая setReadChannel(). QProcess излучает readyRead() при наличии данных в текущем канале чтения. Также он излучает readyReadStandardOutput() при наличии новых данных стандартного вывода, и когда появляются новые данные стандартной ошибки, излучается readyReadStandardError(). Вместо вызова read(), readLine() или getChar() вы можете явно прочитать все данные из любого из двух каналов, вызвав readAllStandardOutput() или readAllStandardError().

Терминология каналов может быть вводящей в заблуждение. Имейте в виду, что каналы вывода процесса соответствуют каналам чтения QProcess, в то время как каналы ввода процесса соответствуют каналам записи QProcess. Это связано с тем, что то, что мы читаем с помощью QProcess, является выводом процесса, а то, что мы записываем, становится вводом процесса.

QProcess может объединить два канала вывода, так что данные стандартного вывода и стандартной ошибки выполняемого процесса оба будут использовать канал стандартного вывода. Вызовите setProcessChannelMode() со значением MergedChannels перед запуском процесса, чтобы активировать эту функцию. У вас также есть возможность перенаправить вывод выполняемого процесса в вызывающий, основной процесс, передав ForwardedChannels в качестве аргумента. Также возможно перенаправить только один из каналов вывода — обычно используется ForwardedErrorChannel, но также существует ForwardedOutputChannel. Обратите внимание, что использование перенаправления каналов обычно является плохой идеей в приложениях GUI — вы должны отображать ошибки графически вместо этого.

Некоторые процессы требуют специальных настроек среды для работы. Вы можете установить переменные среды для своего процесса, вызвав setProcessEnvironment(). Для установки рабочей директории вызовите setWorkingDirectory(). По умолчанию процессы выполняются в текущей рабочей директории вызывающего процесса.

Позиционирование и порядок отображения окон, принадлежащих приложениям GUI, запущенным с помощью QProcess, управляются подлежащей системой окон. Для приложений Qt 5 позиционирование можно указать, используя опцию командной строки -qwindowgeometry; приложения X11 обычно принимают опцию командной строки -geometry.

Примечание: В QNX установка рабочей директории может привести к временному зависанию всех потоков приложения, за исключением потока вызывающего QProcess, во время процесса запуска, из-за ограничения операционной системы.

API синхронного процесса

QProcess предоставляет набор функций, которые позволяют использовать его без цикла событий, приостанавливая вызывающий поток до выдачи определённых сигналов:

• waitForStarted() блокирует выполнение, пока процесс не запустится.
• waitForReadyRead() блокирует выполнение, пока новые данные не станут доступны для чтения в текущем канале чтения.
• waitForBytesWritten() блокирует выполнение, пока один пакет данных не будет записан в процесс.
• waitForFinished() блокирует выполнение, пока процесс не завершится.

Вызов этих функций из основного потока (потока, вызывающего QApplication::exec()) может привести к зависанию вашего пользовательского интерфейса.

Следующий пример запускает gzip для сжатия строки "Qt rocks!", без цикла событий:

    QProcess gzip;
    gzip.start("gzip", QStringList() << "-c");
    if (!gzip.waitForStarted())
        return false;

    gzip.write("Qt rocks!");
    gzip.closeWriteChannel();

    if (!gzip.waitForFinished())
        return false;

    QByteArray result = gzip.readAll();

Примечания для пользователей Windows

Некоторые команды Windows (например, dir) не предоставляются отдельными приложениями, а самим интерпретатором команд. Если вы попытаетесь использовать QProcess для выполнения этих команд напрямую, это не сработает. Одним из возможных решений является выполнение самого интерпретатора команд (cmd.exe на некоторых системах Windows) и просьба к интерпретатору выполнить желаемую команду.

См. также QBuffer, QFile и QTcpSocket.

Документация типов членов

typedef QProcess::CreateProcessArgumentModifier

Примечание: Этот typedef доступен только в настольных версиях Windows.

В Windows QProcess использует функцию Win32 API CreateProcess для запуска дочерних процессов. Хотя QProcess предоставляет удобный способ запуска процессов без необходимости беспокоиться о деталях платформы, в некоторых случаях желательно точно настроить параметры, передаваемые в CreateProcess. Это делается путём определения функции CreateProcessArgumentModifier и передачи её в setCreateProcessArgumentsModifier.

Функция CreateProcessArgumentModifier принимает один параметр: указатель на структуру CreateProcessArguments. Члены этой структуры будут переданы в CreateProcess после вызова функции CreateProcessArgumentModifier.

Следующий пример демонстрирует, как передавать пользовательские флаги в CreateProcess. При запуске консольного процесса B из консольного процесса A, QProcess по умолчанию будет повторно использовать консольное окно процесса A для процесса B. В этом примере для дочернего процесса B создается новое консольное окно со специальной цветовой схемой.

    QProcess process;
    process.setCreateProcessArgumentsModifier([] (QProcess::CreateProcessArguments *args)
    {
        args->flags |= CREATE_NEW_CONSOLE;
        args->startupInfo->dwFlags &= ~STARTF_USESTDHANDLES;
        args->startupInfo->dwFlags |= STARTF_USEFILLATTRIBUTE;
        args->startupInfo->dwFillAttribute = BACKGROUND_BLUE | FOREGROUND_RED
                                           | FOREGROUND_INTENSITY;
    });
    process.start("C:\\Windows\\System32\\cmd.exe", QStringList() << "/k" << "title" << "The Child Process");

См. также QProcess::CreateProcessArguments и setCreateProcessArgumentsModifier().

enum QProcess::ExitStatus

Этот перечисление описывает различные статусы завершения QProcess.

См. также exitStatus().

enum QProcess::InputChannelMode

Это перечисление описывает режимы канала ввода процесса QProcess. Передайте одно из этих значений в setInputChannelMode() для установки текущего режима канала записи.

Это перечисление было добавлено или изменено в Qt 5.2.

См. также setInputChannelMode().

enum QProcess::ProcessChannel

Это перечисление описывает каналы процесса, используемые выполняемым процессом. Передайте одно из этих значений в setReadChannel(), чтобы установить текущий канал чтения QProcess.

См. также setReadChannel().

enum QProcess::ProcessChannelMode

Это перечисление описывает режимы канала вывода процесса QProcess. Передайте одно из этих значений в setProcessChannelMode() для установки текущего режима канала чтения.

Примечание: Windows намеренно подавляет вывод приложений только для графического интерфейса в унаследованных консолях. Это не относится к выводу, перенаправленному в файлы или каналы. Чтобы перенаправить вывод приложений только для графического интерфейса в консоль, тем не менее, вы должны использовать SeparateChannels и выполнить перенаправление самостоятельно, прочитав вывод и записав его в соответствующие каналы вывода.

См. также setProcessChannelMode().

enum QProcess::ProcessError

Это перечисление описывает различные типы ошибок, которые сообщает QProcess.

См. также error().

enum QProcess::ProcessState

Этот перечисление описывает различные состояния объекта QProcess.

См. также state().

Документация по членам-функциям

QProcess::QProcess(QObject *parent = Q_NULLPTR)

Конструирует объект QProcess с заданным parent.

[virtual] QProcess::~QProcess()

Деструктор объекта QProcess, т.е. завершает процесс.

Обратите внимание, что эта функция не вернётся, пока процесс не завершится.

QStringList QProcess::arguments() const

Возвращает аргументы командной строки, с которыми процесс был запущен последний раз.

Функция была добавлена в Qt 5.0.

См. также setArguments() и start().

[virtual] bool QProcess::atEnd() const

Переопределяет QIODevice::atEnd().

Возвращает true, если процесс не запущен и больше данных для чтения недоступно; в противном случае возвращает false.

[virtual] qint64 QProcess::bytesAvailable() const

Переопределяет QIODevice::bytesAvailable().

[virtual] qint64 QProcess::bytesToWrite() const

Переопределяет QIODevice::bytesToWrite().

[virtual] bool QProcess::canReadLine() const

Переопределяет QIODevice::canReadLine().

Эта функция работает с текущим каналом чтения.

См. также readChannel() и setReadChannel().

[virtual] void QProcess::close()

Переопределяет QIODevice::close().

Закрывает все каналы связи с процессом и завершает его. После вызова этой функции QProcess больше не будет излучать readyRead(), и данные больше нельзя читать или записывать.

void QProcess::closeReadChannel(ProcessChannel channel)

Закрывает канал чтения channel. После вызова этой функции QProcess больше не будет получать данные по этому каналу. Любые уже полученные данные по-прежнему доступны для чтения.

Вызовите эту функцию для экономии памяти, если вам не нужен вывод процесса.

См. также closeWriteChannel() и setReadChannel().

void QProcess::closeWriteChannel()

Планирует закрытие канала записи процесса QProcess. Канал закроется после записи всех данных в процесс. После вызова этой функции любые попытки записи в процесс завершатся ошибкой.

Закрытие канала записи необходимо для программ, которые считывают входные данные до закрытия канала. Например, программа «more» используется для отображения текстовых данных в консоли как на Unix, так и на Windows. Но она не будет отображать текстовые данные, пока канал записи QProcess не будет закрыт. Пример:

QProcess more;
more.start("more");
more.write("Text to display");
more.closeWriteChannel();
// QProcess will emit readyRead() once "more" starts printing

Канал записи неявно открывается при вызове start().

См. также closeReadChannel().

CreateProcessArgumentModifier QProcess::createProcessArgumentsModifier() const

Возвращает ранее установленный CreateProcess модификатор функции.

Примечание: Эта функция доступна только на платформе Windows.

Функция была добавлена в Qt 5.7.

См. также setCreateProcessArgumentsModifier() и QProcess::CreateProcessArgumentModifier.

QProcess::ProcessError QProcess::error() const

Возвращает тип последней возникшей ошибки.

См. также state().

[signal] void QProcess::errorOccurred(QProcess::ProcessError error)

Этот сигнал излучается при возникновении ошибки в процессе. Указанная error описывает тип ошибки.

Функция была добавлена в Qt 5.6.

[static] int QProcess::execute(const QString &program, const QStringList &arguments)

Запускает программу program с аргументами arguments в новом процессе, ожидает его завершения и возвращает код завершения процесса. Любые данные, которые новый процесс записывает в консоль, передаются в вызывающий процесс.

Среда и рабочий каталог наследуются от вызывающего процесса.

Обработка аргументов идентична соответствующему перегрузке start().

Если процесс не может быть запущен, возвращается -2. Если процесс завершается аварийно, возвращается -1. В противном случае возвращается код завершения процесса.

См. также start().

[static] int QProcess::execute(const QString &command)

Это перегруженная функция.

Запускает программу command в новом процессе, ожидает его завершения и возвращает код завершения.

Обработка аргументов идентична соответствующему перегрузке start().

После разделения и удаления кавычек из строки command, эта функция ведет себя как перегрузка, принимающая аргументы в виде списка строк.

См. также start().

int QProcess::exitCode() const

Возвращает код завершения последнего завершенного процесса.

Это значение недействительно, если exitStatus() возвращает NormalExit.

QProcess::ExitStatus QProcess::exitStatus() const

Возвращает код завершения последнего завершенного процесса.

В Windows, если процесс был завершен с помощью TerminateProcess() из другого приложения, эта функция по-прежнему вернёт NormalExit, если код завершения не меньше 0.

Функция была добавлена в Qt 4.1.

[signal] void QProcess::finished(int exitCode, QProcess::ExitStatus exitStatus)

Этот сигнал излучается при завершении процесса. exitCode — код завершения процесса (действителен только для нормальных завершений), а exitStatus — статус завершения. После завершения процесса буферы в QProcess всё ещё сохраняются. Вы по-прежнему можете считать любые данные, которые процесс мог записать до завершения.

Примечание: Сигнал finished перегружен в этом классе. Для подключения к этому сигналу с помощью синтаксиса указателя на функцию Qt предоставляет удобную утилиту для получения указателя на функцию, как показано в этом примере:

connect(process, QOverload<int, QProcess::ExitStatus>::of(&QProcess::finished),
    [=](int exitCode, QProcess::ExitStatus exitStatus){ /* ... */ });

См. также exitStatus().

InputChannelMode QProcess::inputChannelMode() const

Возвращает режим канала стандартного ввода процесса QProcess.

Эта функция была добавлена в Qt 5.2.

См. также setInputChannelMode() и InputChannelMode.

[virtual] bool QProcess::isSequential() const

Переопределено из QIODevice::isSequential().

[slot] void QProcess::kill()

Завершает текущий процесс, вызывая его немедленное завершение.

В Windows для завершения используется TerminateProcess, а в Unix и macOS — отправляется сигнал SIGKILL.

См. также terminate().

QString QProcess::nativeArguments() const

Возвращает дополнительные нативные аргументы командной строки для программы.

Примечание: Эта функция доступна только на платформе Windows.

Эта функция была добавлена в Qt 4.7.

См. также setNativeArguments().

[static] QString QProcess::nullDevice()

Пустой (null) устройство операционной системы.

Возвращаемый путь к файлу использует нативные разделители директорий.

Эта функция была добавлена в Qt 5.2.

См. также QProcess::setStandardInputFile(), QProcess::setStandardOutputFile(), и QProcess::setStandardErrorFile().

[virtual] bool QProcess::open(OpenMode mode = ReadWrite)

Переопределено из QIODevice::open().

Запускает программу, заданную setProgram(), с аргументами, заданными setArguments(). Режим OpenMode устанавливается в mode.

Этот метод является псевдонимом для start() и существует только для полного реализации интерфейса, определённого в QIODevice.

См. также start(), setProgram(), и setArguments().

ProcessChannelMode QProcess::processChannelMode() const

Возвращает режим канала стандартного вывода и стандартной ошибки процесса QProcess.

Эта функция была добавлена в Qt 4.2.

См. также setProcessChannelMode(), ProcessChannelMode и setReadChannel().

QProcessEnvironment QProcess::processEnvironment() const

Возвращает среду, которую QProcess передаст своему дочернему процессу, или пустой объект, если среда не была установлена с помощью setEnvironment() или setProcessEnvironment(). Если среда не была установлена, будет использоваться среда вызывающего процесса.

Эта функция была добавлена в Qt 4.6.

См. также setProcessEnvironment(), setEnvironment(), и QProcessEnvironment::isEmpty().

qint64 QProcess::processId() const

Возвращает идентификатор процесса (PID) выполняемого процесса, если он доступен. Если процесс не выполняется, возвращается 0.

Эта функция была добавлена в Qt 5.3.

QString QProcess::program() const

Возвращает программу, с которой процесс был последний раз запущен.

Эта функция была добавлена в Qt 5.0.

См. также setProgram() и start().

QByteArray QProcess::readAllStandardError()

Независимо от текущего канала чтения, эта функция возвращает все данные, доступные из канала стандартной ошибки процесса, как QByteArray.

См. также readyReadStandardError(), readAllStandardOutput(), readChannel() и setReadChannel().

QByteArray QProcess::readAllStandardOutput()

Независимо от текущего канала чтения, эта функция возвращает все данные, доступные из канала стандартного вывода процесса, как QByteArray.

См. также readyReadStandardOutput(), readAllStandardError(), readChannel(), и setReadChannel().

ProcessChannel QProcess::readChannel() const

Возвращает текущий канал чтения процесса QProcess.

См. также setReadChannel().

[virtual protected] qint64 QProcess::readData(char *data, qint64 maxlen)

Переопределено из QIODevice::readData().

[signal] void QProcess::readyReadStandardError()

Этот сигнал испускается, когда процесс предоставил новые данные через канал стандартной ошибки (stderr). Он испускается независимо от текущего канала чтения.

Примечание: Это частный сигнал. Он может использоваться в соединениях сигналов, но не может испускаться пользователем.

См. также readAllStandardError() и readChannel().

[signal] void QProcess::readyReadStandardOutput()

Этот сигнал испускается, когда процесс предоставил новые данные через канал стандартного вывода (stdout). Он испускается независимо от текущего канала чтения.

Примечание: Это частный сигнал. Он может использоваться в соединениях сигналов, но не может испускаться пользователем.

См. также readAllStandardOutput() и readChannel().

void QProcess::setArguments(const QStringList &arguments)

Устанавливает arguments для передачи вызываемой программе при запуске процесса. Эта функция должна быть вызвана перед start().

Эта функция была добавлена в Qt 5.1.

См. также start(), setProgram(), и arguments().

void QProcess::setCreateProcessArgumentsModifier(CreateProcessArgumentModifier modifier)

Устанавливает modifier для вызова API CreateProcess Win32. Передайте QProcess::CreateProcessArgumentModifier() для удаления ранее установленного.

Примечание: Эта функция доступна только на платформе Windows и требует C++11.

Эта функция была добавлена в Qt 5.7.

См. также createProcessArgumentsModifier() и QProcess::CreateProcessArgumentModifier.

void QProcess::setInputChannelMode(InputChannelMode mode)

Устанавливает режим канала стандартного ввода процесса QProcess в указанный mode. Этот режим будет использован в следующий раз, когда будет вызван start().

Эта функция была добавлена в Qt 5.2.

См. также inputChannelMode() и InputChannelMode.

void QProcess::setNativeArguments(const QString &arguments)

Это перегруженная функция.

Устанавливает дополнительные нативные аргументы командной строки arguments для программы.

В операционных системах, где системный API для передачи аргументов командной строки дочернему процессу использует одну строку, можно представить командные строки, которые не могут быть переданы через основанный на списках API QProcess. В таких случаях эта функция должна использоваться для установки строки, которая добавляется к строке, составленной из обычного списка аргументов, с разделителем пробела.

Примечание: Эта функция доступна только на платформе Windows.

Эта функция была добавлена в Qt 4.7.

См. также nativeArguments().

void QProcess::setProcessChannelMode(ProcessChannelMode mode)

Устанавливает режим канала стандартного вывода и стандартной ошибки процесса QProcess в указанный mode. Этот режим будет использован в следующий раз, когда будет вызван start(). Например:

QProcess builder;
builder.setProcessChannelMode(QProcess::MergedChannels);
builder.start("make", QStringList() << "-j2");

if (!builder.waitForFinished())
    qDebug() << "Make failed:" << builder.errorString();
else
    qDebug() << "Make output:" << builder.readAll();

Эта функция была добавлена в Qt 4.2.

См. также processChannelMode(), ProcessChannelMode и setReadChannel().

void QProcess::setProcessEnvironment(const QProcessEnvironment &environment)

Устанавливает environment, которое QProcess передаст дочернему процессу.

Например, следующий код добавляет переменную среды TMPDIR:

QProcess process;
QProcessEnvironment env = QProcessEnvironment::systemEnvironment();
env.insert("TMPDIR", "C:\\MyApp\\temp"); // Add an environment variable
process.setProcessEnvironment(env);
process.start("myapp");

Обратите внимание, как на Windows имена переменных среды нечувствительны к регистру.

Эта функция была введена в Qt 4.6.

См. также processEnvironment(), QProcessEnvironment::systemEnvironment и setEnvironment().

[protected] void QProcess::setProcessState(ProcessState state)

Устанавливает текущее состояние QProcess в указанное state.

См. также state().

void QProcess::setProgram(const QString &program)

Устанавливает program для использования при запуске процесса. Эту функцию необходимо вызвать перед start().

Эта функция была введена в Qt 5.1.

См. также start(), setArguments() и program().

void QProcess::setReadChannel(ProcessChannel channel)

Устанавливает текущий канал чтения QProcess на заданный channel. Текущий канал ввода используется функциями read(), readAll(), readLine() и getChar(). Он также определяет, какой канал запускает QProcess для излучения сигнала readyRead().

См. также readChannel().

void QProcess::setStandardErrorFile(const QString &fileName, OpenMode mode = Truncate)

Перенаправляет стандартный вывод ошибки процесса в файл fileName. При включенном перенаправлении канал чтения стандартного вывода ошибок закрывается: чтение из него с помощью read() всегда завершится ошибкой, как и readAllStandardError(). Файл будет добавлен в конец, если mode равно Append, в противном случае, он будет обнулен.

См. setStandardOutputFile() для получения дополнительной информации о том, как открывается файл.

Примечание: если setProcessChannelMode() был вызван со значением QProcess::MergedChannels, эта функция не оказывает никакого влияния.

Эта функция была введена в Qt 4.2.

См. также setStandardInputFile(), setStandardOutputFile() и setStandardOutputProcess().

void QProcess::setStandardInputFile(const QString &fileName)

Перенаправляет стандартный ввод процесса в файл, указанный в fileName. При перенаправлении ввода объект QProcess будет в режиме только для чтения (вызов write() приведет к ошибке).

Чтобы сразу сделать процесс чтением EOF, передайте nullDevice() сюда. Это чище, чем использовать closeWriteChannel() перед записью каких-либо данных, так как это может быть настроено до запуска процесса.

Если файл fileName не существует в момент вызова start() или не доступен для чтения, запуск процесса завершится ошибкой.

Вызов setStandardInputFile() после запуска процесса не оказывает никакого влияния.

Эта функция была введена в Qt 4.2.

См. также setStandardOutputFile(), setStandardErrorFile() и setStandardOutputProcess().

void QProcess::setStandardOutputFile(const QString &fileName, OpenMode mode = Truncate)

Перенаправляет стандартный вывод процесса в файл fileName. При перенаправлении канал чтения стандартного вывода закрывается: чтение из него с помощью read() всегда завершится ошибкой, как и readAllStandardOutput().

Чтобы отбросить весь стандартный вывод из процесса, передайте nullDevice() сюда. Это более эффективно, чем просто никогда не читать стандартный вывод, так как никакие буферы QProcess не заполняются.

Если файл fileName не существует в момент вызова start(), он будет создан. Если он не может быть создан, запуск завершится ошибкой.

Если файл существует и mode равен QIODevice::Truncate, файл будет обнулен. В противном случае (если mode равен QIODevice::Append), файл будет добавлен в конец.

Вызов setStandardOutputFile() после запуска процесса не оказывает никакого влияния.

Эта функция была введена в Qt 4.2.

См. также setStandardInputFile(), setStandardErrorFile() и setStandardOutputProcess().

void QProcess::setStandardOutputProcess(QProcess *destination)

Подключает поток стандартного вывода этого процесса к потоку стандартного ввода процесса destination.

Следующая команда оболочки:

command1 | command2

Может быть выполнена с помощью QProcess следующим кодом:

QProcess process1;
QProcess process2;

process1.setStandardOutputProcess(&process2);

process1.start("command1");
process2.start("command2");

Эта функция была введена в Qt 4.2.

void QProcess::setWorkingDirectory(const QString &dir)

Устанавливает рабочую директорию в dir. QProcess запустит процесс в этой директории. По умолчанию процесс запускается в рабочей директории вызывающего процесса.

Примечание: На QNX это может привести к временному зависанию всех потоков приложения.

См. также workingDirectory() и start().

[virtual protected] void QProcess::setupChildProcess()

Эта функция вызывается в контексте дочернего процесса непосредственно перед выполнением программы на Unix или macOS (т.е., после fork(), но перед execve()). Переопределите эту функцию, чтобы выполнить последнюю инициализацию дочернего процесса. Пример:

class SandboxProcess : public QProcess
{
    ...
 protected:
     void setupChildProcess();
    ...
};

void SandboxProcess::setupChildProcess()
{
    // Drop all privileges in the child process, and enter
    // a chroot jail.
#if defined Q_OS_UNIX
    ::setgroups(0, 0);
    ::chroot("/etc/safe");
    ::chdir("/");
    ::setgid(safeGid);
    ::setuid(safeUid);
    ::umask(0);
#endif
}

Вы не можете завершить процесс (вызвав exit(), например) из этой функции. Если вам нужно остановить программу до начала выполнения, ваш обходной путь заключается в излучении finished() и затем вызове exit().

Предупреждение: Эта функция вызывается QProcess только на Unix и macOS. На Windows и QNX она не вызывается.

void QProcess::start(const QString &program, const QStringList &arguments, OpenMode mode = ReadWrite)

Запускает заданную program в новом процессе, передавая аргументы командной строки в arguments.

Объект QProcess сразу перейдет в состояние запуска. Если процесс запустится успешно, QProcess излучит started; в противном случае, будет излучен errorOccurred().

Примечание: Процессы запускаются асинхронно, что означает, что сигналы started и errorOccurred могут быть задержаны. Используйте waitForStarted, чтобы убедиться, что процесс запустился (или не смог запуститься) и эти сигналы были излучены.

Примечание: Дальнейшее разделение аргументов не выполняется.

Windows: Аргументы заключаются в кавычки и объединяются в строку команд, совместимую с функцией CommandLineToArgvW() Windows. Для программ с различными требованиями к цитированию командной строки используйте setNativeArguments(). Отличительной программой, которая не следует правилам CommandLineToArgvW(), является cmd.exe и, как следствие, все скрипты пакетных файлов.

Значение OpenMode устанавливается в mode.

Если в объекте QProcess уже запущен процесс, может быть выведено предупреждение в консоль, а существующий процесс будет продолжать работать без изменений.

См. также processId(), started(), waitForStarted() и setNativeArguments().

void QProcess::start(const QString &command, OpenMode mode = ReadWrite)

Это перегруженная функция.

Запускает команду command в новом процессе. Значение OpenMode устанавливается в mode.

command — это единственная строка текста, содержащая имя программы и ее аргументы. Аргументы разделены одним или несколькими пробелами. Например:

QProcess process;
process.start("del /s *.txt");
// same as process.start("del", QStringList() << "/s" << "*.txt");
...

Аргументы, содержащие пробелы, необходимо заключить в кавычки, чтобы они корректно передавались новому процессу. Например:

QProcess process;
process.start("dir \"My Documents\"");

Литеральные кавычки в строке command представлены тройными кавычками. Например:

QProcess process;
process.start("dir \"Epic 12\"\"\" Singles\"");

После разделения и удаления кавычек из строки command, эта функция ведет себя как перегрузка, принимающая аргументы в виде списка строк.

Вы можете отключить эту перегрузку, определив QT_NO_PROCESS_COMBINED_ARGUMENT_START при компиляции ваших приложений. Это может быть полезно, если вы хотите убедиться, что аргументы не разделяются непреднамеренно, например. Практически во всех случаях использование другой перегрузки предпочтительнее.

В операционных системах, где системный API для передачи аргументов командной строки дочернему процессу изначально использует одну строку (Windows), можно представить командные строки, которые не могут быть переданы с помощью портативного API на основе списков QProcess. В этих редких случаях вам необходимо использовать setProgram() и setNativeArguments() вместо этой функции.

void QProcess::start(OpenMode mode = ReadWrite)

Это перегруженная функция.

Запускает программу, заданную с помощью setProgram(), с аргументами, заданными с помощью setArguments(). Режим OpenMode устанавливается в mode.

Эта функция была введена в Qt 5.1.

См. также open(), setProgram() и setArguments().

[static] bool QProcess::startDetached(const QString &program, const QStringList &arguments, const QString &workingDirectory = QString(), qint64 *pid = Q_NULLPTR)

Запускает программу program с аргументами arguments в новом процессе и отделяется от него. Возвращает true при успехе; в противном случае возвращает false. Если вызывающий процесс завершается, отделённый процесс продолжит работу без изменений.

Обработка аргументов идентична соответствующей перегрузке start().

Unix: Запущенный процесс будет работать в своей собственной сессии и действовать как демон.

Процесс будет запущен в каталоге workingDirectory. Если workingDirectory пуста, каталог работы наследуется от вызывающего процесса.

Примечание: В QNX это может привести к временному зависанию всех потоков приложения.

Если функция выполняется успешно, то *pid устанавливается в идентификатор процесса запущенного процесса.

См. также start().

[static] bool QProcess::startDetached(const QString &command)

Это перегруженная функция.

Запускает команду command в новом процессе и отделяется от него. Возвращает true при успехе; в противном случае возвращает false.

Обработка аргументов идентична соответствующей перегрузке start().

После разделения и удаления кавычек из строки command, эта функция ведет себя как перегрузка, принимающая аргументы в виде списка строк.

См. также start(const QString &command, OpenMode mode).

[signal] void QProcess::started()

Этот сигнал испускается QProcess, когда процесс запущен, а state() возвращает Running.

Примечание: Это частный сигнал. Он может использоваться в соединениях сигналов, но не может испускаться пользователем.

QProcess::ProcessState QProcess::state() const

Возвращает текущее состояние процесса.

См. также stateChanged() и error().

[signal] void QProcess::stateChanged(QProcess::ProcessState newState)

Этот сигнал испускается всякий раз, когда изменяется состояние QProcess. Аргумент newState — это состояние, в которое перешёл QProcess.

Примечание: Это частный сигнал. Он может использоваться в соединениях сигналов, но не может испускаться пользователем.

[static] QStringList QProcess::systemEnvironment()

Возвращает окружение вызывающего процесса в виде списка пар ключ=значение. Пример:

QStringList environment = QProcess::systemEnvironment();
// environment = {"PATH=/usr/bin:/usr/local/bin",
//                "USER=greg", "HOME=/home/greg"}

Эта функция не кэширует системное окружение. Поэтому возможно получить обновлённую версию окружения, если были вызваны низкоуровневые функции C-библиотеки, такие как setenv или putenv.

Однако обратите внимание, что повторные вызовы этой функции будут создавать список переменных окружения заново, что является нетривиальной операцией.

Примечание: Для нового кода рекомендуется использовать QProcessEnvironment::systemEnvironment()

Эта функция была введена в Qt 4.1.

См. также QProcessEnvironment::systemEnvironment() и setProcessEnvironment().

[slot] void QProcess::terminate()

Попытка завершить процесс.

Процесс может не завершиться в результате вызова этой функции (ему предоставляется возможность запросить у пользователя сохранение любых несохранённых файлов и т. п.).

В Windows terminate() отправляет сообщение WM_CLOSE во все окна верхнего уровня процесса, а затем — в сам основной поток процесса. В Unix и macOS отправляется сигнал SIGTERM.

Консольные приложения в Windows, которые не запускают цикл обработки событий или цикл обработки событий не обрабатывает сообщение WM_CLOSE, могут быть завершены только вызовом kill().

См. также kill().

[virtual] bool QProcess::waitForBytesWritten(int msecs = 30000)

Переопределено из QIODevice::waitForBytesWritten().

bool QProcess::waitForFinished(int msecs = 30000)

Задерживает выполнение, пока процесс не завершится и не будет отправлен сигнал finished(), или пока не пройдёт msecs миллисекунд.

Возвращает true, если процесс завершился; в противном случае возвращает false (если операция истекла, произошла ошибка или этот QProcess уже завершён).

Эта функция может работать без цикла обработки событий. Она полезна при написании приложений без графического интерфейса и при выполнении операций ввода/вывода в потоке без графического интерфейса.

Предупреждение: Вызов этой функции из главного (графического) потока может привести к зависанию пользовательского интерфейса.

Если msecs равно -1, эта функция не будет ожидать таймаута.

См. также finished(), waitForStarted(), waitForReadyRead() и waitForBytesWritten().

[virtual] bool QProcess::waitForReadyRead(int msecs = 30000)

Переопределено из QIODevice::waitForReadyRead().

bool QProcess::waitForStarted(int msecs = 30000)

Задерживает выполнение, пока процесс не запустится и не будет отправлен сигнал started(), или пока не пройдёт msecs миллисекунд.

Возвращает true, если процесс был запущен успешно; в противном случае возвращает false (если операция истекла или произошла ошибка).

Эта функция может работать без цикла обработки событий. Она полезна при написании приложений без графического интерфейса и при выполнении операций ввода/вывода в потоке без графического интерфейса.

Предупреждение: Вызов этой функции из главного (графического) потока может привести к зависанию пользовательского интерфейса.

Если msecs равно -1, эта функция не будет ожидать таймаута.

Примечание: В некоторых операционных системах UNIX эта функция может вернуть true, но процесс может позже сообщить об ошибке QProcess::FailedToStart.

См. также started(), waitForReadyRead(), waitForBytesWritten() и waitForFinished().

QString QProcess::workingDirectory() const

Если QProcess был назначен рабочий каталог, эта функция возвращает рабочий каталог, в который войдёт QProcess перед запуском программы. В противном случае (т. е. каталог не был назначен) возвращается пустая строка, и QProcess будет использовать текущий рабочий каталог приложения.

См. также setWorkingDirectory().

[virtual protected] qint64 QProcess::writeData(const char *data, qint64 len)

Переопределено из QIODevice::writeData().