Класс QProcess

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

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

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

Открытые типы

Открытые функции

Переопределенные открытые функции

Public Slots

Signals

Static Public Members

Protected Functions

Reimplemented Protected Functions

Detailed Description

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

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

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

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

[private signal] void QProcess::readyReadStandardOutput()

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

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

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

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

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

Эта функция была добавлена в 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

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

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

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 Win32 CreateProcess. Передайте 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() приведет к ошибке).

Чтобы процесс сразу прочитал конец файла, передайте 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 немедленно перейдет в состояние Запускается. Если процесс запустится успешно, QProcess отправит сигнал started; в противном случае, будет послан сигнал errorOccurred().

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

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

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

Режим открытия установлен в mode.

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

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

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

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

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

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

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

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

Запускает команду command в новом процессе. Режим открытия установлен в 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 устанавливается в идентификатор процесса запущенного процесса; в противном случае он устанавливается в -1. Обратите внимание, что дочерний процесс может завершиться, и PID может стать недействительным без уведомления. Кроме того, после завершения дочернего процесса тот же PID может быть повторно использован другим процессом. Код пользователя должен быть осторожным при использовании этой переменной, особенно если предполагается принудительное завершение процесса средствами операционной системы.

Только следующие установщики свойств поддерживаются startDetached():

• setArguments()
• setCreateProcessArgumentsModifier()
• setNativeArguments()
• setProcessEnvironment()
• setProgram()
• setStandardErrorFile()
• setStandardInputFile()
• setStandardOutputFile()
• setProcessChannelMode(QProcess::MergedChannels)
• setStandardOutputProcess()
• 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 уже завершён).

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

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

Если 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 (если операция истекла или произошла ошибка).

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

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

Если 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).