Класс QProcess

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

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

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

Типы публичного доступа

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

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

Public Slots

Signals

Static Public Members

Protected Functions

Reimplemented Protected Functions

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

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

Для запуска процесса передайте имя и аргументы командной строки программы, которую вы хотите запустить, в качестве аргументов методу 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.

Общение через каналы

Процессы имеют два предварительно определенных канала вывода: канал стандартного вывода (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.

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

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

[since 5.2] перечисление QProcess::InputChannelMode

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

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

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

enum QProcess::ProcessChannel

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

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

enum QProcess::ProcessChannelMode

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

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

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

enum QProcess::ProcessError

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

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

enum QProcess::ProcessState

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

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

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

QProcess::QProcess(QObject *parent = nullptr)

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

[signal, since 5.6] void QProcess::errorOccurred(QProcess::ProcessError error)

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

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

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

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

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

[slot] void QProcess::kill()

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

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

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

[private signal] void QProcess::readyReadStandardError()

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

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

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

[private signal] void QProcess::readyReadStandardOutput()

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

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

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

[private signal] void QProcess::started()

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

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

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

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

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

[slot] void QProcess::terminate()

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

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

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

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

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

[virtual] QProcess::~QProcess()

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

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

[since 5.0] QStringList QProcess::arguments() const

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

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

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

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

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

[since 6.0] std::function<void ()> QProcess::childProcessModifier() const

Возвращает функцию-модификатор, ранее установленную с помощью вызова setChildProcessModifier().

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

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

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

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

[since 5.7] QProcess::CreateProcessArgumentModifier QProcess::createProcessArgumentsModifier() const

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

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

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

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

QProcess::ProcessError QProcess::error() const

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

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

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

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

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

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

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

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

int QProcess::exitCode() const

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

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

QProcess::ExitStatus QProcess::exitStatus() const

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

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

[since 5.2] QProcess::InputChannelMode QProcess::inputChannelMode() const

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

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

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

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

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

QString QProcess::nativeArguments() const

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

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

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

[static, since 5.2] QString QProcess::nullDevice()

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

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

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

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

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

Переопределяет: QIODevice::open(QIODeviceBase::OpenMode mode).

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

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

Возвращает true если программа запущена.

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

QProcess::ProcessChannelMode QProcess::processChannelMode() const

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

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

QProcessEnvironment QProcess::processEnvironment() const

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

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

[since 5.3] qint64 QProcess::processId() const

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

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

[since 5.0] 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(char *data, qint64 maxSize).

[since 5.1] void QProcess::setArguments(const QStringList &arguments)

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

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

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

[since 6.0] void QProcess::setChildProcessModifier(const std::function<void ()> &modifier)

Устанавливает функцию modifier для дочернего процесса для систем Unix (включая macOS; для Windows см. setCreateProcessArgumentsModifier()). Функция, содержащаяся в аргументе modifier, будет вызвана в дочернем процессе после завершения fork() и QProcess настроит стандартные дескрипторы файлов для дочернего процесса, но перед execve(), внутри start(). Модификатор полезен для изменения определённых свойств дочернего процесса, таких как настройка дополнительных дескрипторов файлов или закрытие других, изменение уровня nice, отключение от управляемого TTY и т. д.

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

void runSandboxed(const QString &name, const QStringList &arguments)
{
    QProcess proc;
    proc.setChildProcessModifier([] {
        // Drop all privileges in the child process, and enter
        // a chroot jail.
        ::setgroups(0, nullptr);
        ::chroot("/run/safedir");
        ::chdir("/");
        ::setgid(safeGid);
        ::setuid(safeUid);
        ::umask(077);
    });
    proc.start(name, arguments);
    proc.waitForFinished();
}

Если функция модификатора нуждается в завершении процесса, используйте _exit(), а не exit().

Примечание: В многопоточных приложениях эта функция должна быть внимательна, чтобы не вызывать функции, которые могут блокировать мьютексы, которые могут использоваться в других потоках (в общем случае рекомендуется использовать только функции, определённые POSIX как «безопасные для обработки сигналов в асинхронных событиях»). Большая часть API Qt небезопасна внутри этого обратного вызова, включая qDebug(), и может привести к тупиковым ситуациям.

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

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

[since 5.7] void QProcess::setCreateProcessArgumentsModifier(QProcess::CreateProcessArgumentModifier modifier)

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

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

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

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

[since 5.2] 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.

См. также 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();

См. также 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 имена переменных окружения нечувствительны к регистру.

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

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

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

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

[since 5.1] 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, QIODeviceBase::OpenMode mode = Truncate)

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

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

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

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

void QProcess::setStandardInputFile(const QString &fileName)

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

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

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

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

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

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

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

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

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

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

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

См. также 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");

void QProcess::setWorkingDirectory(const QString &dir)

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

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

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

[static, since 5.15] QStringList QProcess::splitCommand(QStringView command)

Разбивает строку command на список маркеров и возвращает этот список.

Маркеры с пробелами могут быть заключены в двойные кавычки; три последовательные двойные кавычки представляют собой сам символ кавычки.

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

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

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

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

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

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

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

Режим OpenMode устанавливается в mode.

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

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

[since 5.1] void QProcess::start(QIODeviceBase::OpenMode mode = ReadWrite)

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

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

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

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

[since 6.0] void QProcess::startCommand(const QString &command, QIODeviceBase::OpenMode mode = ReadWrite)

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

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

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

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

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

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

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

После разделения и удаления кавычек из строки command, эта функция ведет себя как start().

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

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

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

[since 5.10] bool QProcess::startDetached(qint64 *pid = nullptr)

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

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

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

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

Если функция выполняется успешно, то *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).

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

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

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

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

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

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

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

QProcess::ProcessState QProcess::state() const

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

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

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

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

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

Переопределяет: QIODevice::waitForBytesWritten(int msecs).

bool QProcess::waitForFinished(int msecs = 30000)

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

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

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

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

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

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

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

Переопределяет: QIODevice::waitForReadyRead(int msecs).

bool QProcess::waitForStarted(int msecs = 30000)

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

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

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

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

Если 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(const char *data, qint64 maxSize).