Класс QProcess

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

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

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

Публичные типы

Публичные функции

Реализованные публичные функции

• 44 общедоступных функций, унаследованных от QIODevice
• 32 общедоступных функций, унаследованных от QObject

Общедоступные слоты

• 1 общедоступный слот, унаследованный от QObject

Сигналы

• 6 сигналов, унаследованных от QIODevice
• 2 сигналов, унаследованных от QObject

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

• 10 статических общедоступных членов, унаследованных от QObject

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

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

• 5 защищённых функций, унаследованных от QIODevice
• 9 защищённых функций, унаследованных от QObject

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

Макросы

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

• 1 свойство, унаследованное от 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().

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

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

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

Позиционирование и порядок отображения окон, принадлежащих приложениям с графическим интерфейсом, запущенным с помощью 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 = nullptr)

Создаёт объект QProcess с заданным parent.

[virtual] QProcess::~QProcess()

Удаляет объект QProcess, т.е. завершает процесс.

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

QStringList QProcess::arguments() const

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

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

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

[override virtual] bool QProcess::atEnd() const

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

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

[override virtual] qint64 QProcess::bytesAvailable() const

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

[override virtual] qint64 QProcess::bytesToWrite() const

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

[override virtual] bool QProcess::canReadLine() const

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

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

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

[override virtual] void QProcess::close()

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

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

void QProcess::closeReadChannel(QProcess::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().

QProcess::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().

QProcess::InputChannelMode QProcess::inputChannelMode() const

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

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

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

[override virtual] bool QProcess::isSequential() const

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

[slot] void QProcess::kill()

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

В Windows kill() использует TerminateProcess, а в Unix и macOS процессу отправляется сигнал SIGKILL.

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

QString QProcess::nativeArguments() const

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

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

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

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

[static] QString QProcess::nullDevice()

Пустой файл операционной системы.

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

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

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

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

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

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

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

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

QProcess::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

Возвращает системный идентификатор процесса для запущенного процесса, если доступен. Если процесс в данный момент не запущен, возвращается 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().

QProcess::ProcessChannel QProcess::readChannel() const

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

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

[override 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(QProcess::CreateProcessArgumentModifier modifier)

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

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

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

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

void QProcess::setInputChannelMode(QProcess::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(QProcess::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(QProcess::ProcessState state)

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

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

void QProcess::setProgram(const QString &program)

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

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

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

void QProcess::setReadChannel(QProcess::ProcessChannel channel)

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

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

void QProcess::setStandardErrorFile(const QString &fileName, QIODevice::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, QIODevice::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() override;
    ...
};

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, QIODevice::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 &команда, QIODevice::OpenMode режим = ReadWrite)

Это перегруженный метод.

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

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

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

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

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

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

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

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

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

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

void QProcess::start(QIODevice::OpenMode режим = ReadWrite)

Это перегруженный метод.

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

Этот метод был добавлен в Qt 5.1.

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

bool QProcess::startDetached(qint64 *pid = nullptr)

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

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

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

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

Если функция выполняется успешно, то *pid устанавливается в идентификатор процесса запущенного процесса. Обратите внимание, что дочерний процесс может завершиться, и PID может стать недействительным без предупреждения. Кроме того, после завершения дочернего процесса тот же PID может быть повторно использован другим процессом. Код пользователя должен быть осторожным при использовании этой переменной, особенно если планируется принудительное завершение процесса операционной системой.

Следующие методы свойств поддерживаются startDetached():

• setArguments()
• setCreateProcessArgumentsModifier()
• setNativeArguments()
• setProcessEnvironment()
• setProgram()
• setStandardErrorFile()
• setStandardInputFile()
• setStandardOutputFile()
• setWorkingDirectory()

Все остальные свойства объекта QProcess игнорируются.

Примечание: Вызываемый процесс наследует окно консоли вызывающего процесса. Для подавления вывода консоли перенаправьте стандартный/ошибочный вывод в QProcess::nullDevice().

Этот метод был добавлен в Qt 5.10.

См. также start(), startDetached(const QString &program, const QStringList &arguments, const QString &workingDirectory, qint64 *pid), и startDetached(const QString &command).

[static] bool QProcess::startDetached(const QString &программа, const QStringList &аргументы, const QString &каталогРаботы = QString(), qint64 *pid = nullptr)

Этот метод перегружает startDetached().

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

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

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

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

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

[static] bool QProcess::startDetached(const QString &команда)

Этот метод перегружает startDetached().

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

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

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

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

[signal] void QProcess::started()

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

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

QProcess::ProcessState QProcess::state() const

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

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

[signal] void QProcess::stateChanged(QProcess::ProcessState новоеСостояние)

Этот сигнал испускается всякий раз, когда состояние объекта QProcess меняется. Аргумент новоеСостояние — это состояние, в которое перешёл объект 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().

[override 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().

[override 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().

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

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