QProcess Class
La clase QProcess se utiliza para iniciar programas externos y comunicarse con ellos. Más información...
| Encabezado: | #include <QProcess> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Heredado de: | QIODevice |
- Lista de todos los miembros, incluidos los heredados
- Miembros obsoletos
- QProcess forma parte de Entrada/Salida y Redes.
Nota: Todas las funciones de esta clase son reentrantes.
Tipos públicos
| struct | CreateProcessArguments |
(since 6.6) struct | UnixProcessParameters |
| CreateProcessArgumentModifier | |
| enum | ExitStatus { NormalExit, CrashExit } |
| enum | InputChannelMode { ManagedInputChannel, ForwardedInputChannel } |
| enum | ProcessChannel { StandardOutput, StandardError } |
| enum | ProcessChannelMode { SeparateChannels, MergedChannels, ForwardedChannels, ForwardedErrorChannel, ForwardedOutputChannel } |
| enum | ProcessError { FailedToStart, Crashed, Timedout, WriteError, ReadError, UnknownError } |
| enum | ProcessState { NotRunning, Starting, Running } |
(since 6.6) enum class | UnixProcessFlag { CloseFileDescriptors, CreateNewSession, DisconnectControllingTerminal, IgnoreSigPipe, ResetIds, …, DisableCoreDumps } |
| flags | UnixProcessFlags |
Funciones públicas
| QProcess(QObject *parent = nullptr) | |
| virtual | ~QProcess() |
| QStringList | arguments() const |
(since 6.0) std::function<void ()> | childProcessModifier() const |
| void | closeReadChannel(QProcess::ProcessChannel channel) |
| void | closeWriteChannel() |
| QProcess::CreateProcessArgumentModifier | createProcessArgumentsModifier() const |
| QProcess::ProcessError | error() const |
| int | exitCode() const |
| QProcess::ExitStatus | exitStatus() const |
(since 6.7) void | failChildProcessModifier(const char *description, int error = 0) |
| QProcess::InputChannelMode | inputChannelMode() const |
| QString | nativeArguments() const |
| QProcess::ProcessChannelMode | processChannelMode() const |
| QProcessEnvironment | processEnvironment() const |
| qint64 | processId() const |
| QString | program() const |
| QByteArray | readAllStandardError() |
| QByteArray | readAllStandardOutput() |
| QProcess::ProcessChannel | readChannel() const |
| void | setArguments(const QStringList &arguments) |
(since 6.0) void | setChildProcessModifier(const std::function<void ()> &modifier) |
| void | setCreateProcessArgumentsModifier(QProcess::CreateProcessArgumentModifier modifier) |
| void | setInputChannelMode(QProcess::InputChannelMode mode) |
| void | setNativeArguments(const QString &arguments) |
| void | setProcessChannelMode(QProcess::ProcessChannelMode mode) |
| void | setProcessEnvironment(const QProcessEnvironment &environment) |
| void | setProgram(const QString &program) |
| void | setReadChannel(QProcess::ProcessChannel channel) |
| void | setStandardErrorFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate) |
| void | setStandardInputFile(const QString &fileName) |
| void | setStandardOutputFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate) |
| void | setStandardOutputProcess(QProcess *destination) |
(since 6.6) void | setUnixProcessParameters(const QProcess::UnixProcessParameters ¶ms) |
(since 6.6) void | setUnixProcessParameters(QProcess::UnixProcessFlags flagsOnly) |
| void | setWorkingDirectory(const QString &dir) |
| void | start(const QString &program, const QStringList &arguments = {}, QIODeviceBase::OpenMode mode = ReadWrite) |
| void | start(QIODeviceBase::OpenMode mode = ReadWrite) |
(since 6.0) void | startCommand(const QString &command, QIODeviceBase::OpenMode mode = ReadWrite) |
| bool | startDetached(qint64 *pid = nullptr) |
| QProcess::ProcessState | state() const |
(since 6.6) QProcess::UnixProcessParameters | unixProcessParameters() const |
| bool | waitForFinished(int msecs = 30000) |
| bool | waitForStarted(int msecs = 30000) |
| QString | workingDirectory() const |
Funciones públicas reimplementadas
| virtual qint64 | bytesToWrite() const override |
| virtual void | close() override |
| virtual bool | isSequential() const override |
| virtual bool | open(QIODeviceBase::OpenMode mode = ReadWrite) override |
| virtual bool | waitForBytesWritten(int msecs = 30000) override |
| virtual bool | waitForReadyRead(int msecs = 30000) override |
Ranuras públicas
Señales
| void | errorOccurred(QProcess::ProcessError error) |
| void | finished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit) |
| void | readyReadStandardError() |
| void | readyReadStandardOutput() |
| void | started() |
| void | stateChanged(QProcess::ProcessState newState) |
Miembros públicos estáticos
| int | execute(const QString &program, const QStringList &arguments = {}) |
| QString | nullDevice() |
| QStringList | splitCommand(QStringView command) |
| bool | startDetached(const QString &program, const QStringList &arguments = {}, const QString &workingDirectory = QString(), qint64 *pid = nullptr) |
| QStringList | systemEnvironment() |
Funciones protegidas
| void | setProcessState(QProcess::ProcessState state) |
Funciones protegidas reimplementadas
| virtual qint64 | readData(char *data, qint64 maxlen) override |
Descripción detallada
Ejecución de un proceso
Para iniciar un proceso, pasa el nombre y los argumentos de la línea de comandos del programa que deseas ejecutar como argumentos a ` start()`. Los argumentos se proporcionan como cadenas individuales en un ` QStringList`.
Como alternativa, puede configurar el programa para que se ejecute con setProgram() y setArguments(), y a continuación llamar a start() o open().
Por ejemplo, el siguiente fragmento de código ejecuta el ejemplo del reloj analógico con el estilo «Fusion» en plataformas X11, pasando cadenas que contienen «-style» y «fusion» como dos elementos de la lista de argumentos:
QObject *parent = new QObject;
...
QString program = "./path/to/Qt/examples/widgets/analogclock";
QStringList arguments;
arguments << "-style" << "fusion";
QProcess *myProcess = new QProcess(parent);
myProcess->start(program, arguments);A continuación, QProcess pasa al estado « Starting » y, una vez que el programa se ha iniciado, QProcess pasa al estado « Running » y emite started().
QProcess te permite tratar un proceso como un dispositivo de E/S secuencial. Puedes escribir en el proceso y leer de él del mismo modo que accederías a una conexión de red utilizando ` QTcpSocket`. A continuación, puedes escribir en la entrada estándar del proceso llamando a ` write()`, y leer la salida estándar llamando a ` read()`, ` readLine()` y ` getChar()`. Dado que hereda de ` QIODevice`, QProcess también puede utilizarse como fuente de entrada para ` QXmlReader`, o para generar datos que se vayan a cargar mediante ` QNetworkAccessManager`.
Cuando el proceso finaliza, QProcess vuelve al estado « NotRunning » (el estado inicial) y emite la señal « finished()».
La señal finished() proporciona como argumentos el código de salida y el estado de salida del proceso; además, se puede llamar a exitCode() para obtener el código de salida del último proceso que finalizó, y a exitStatus() para obtener su estado de salida. Si se produce un error en cualquier momento, QProcess emitirá la señal errorOccurred(). También puedes llamar a ` error()` para conocer el tipo de error que se produjo en último lugar, y a ` state()` para conocer el estado actual del proceso.
Nota: QProcess no es compatible con VxWorks, iOS, tvOS ni watchOS.
Búsqueda del ejecutable
El programa que se va a ejecutar se puede establecer llamando a ` setProgram()` o directamente en la llamada a ` start()`. El efecto de llamar a ` start()` con el nombre del programa y los argumentos es equivalente a llamar a ` setProgram()` y ` setArguments()` antes de esa función y, a continuación, llamar a la sobrecarga sin esos parámetros.
QProcess interpreta el nombre del programa de una de estas tres formas diferentes, de manera similar a como funcionan los shells de Unix y el intérprete de comandos de Windows en sus propias líneas de comandos:
- Si el nombre del programa es una ruta absoluta, ese es exactamente el ejecutable que se iniciará y QProcess no realiza ninguna búsqueda.
- Si el nombre del programa es una ruta relativa con más de un componente de ruta (es decir, contiene al menos una barra), el directorio de inicio desde el que se busca esa ruta relativa depende del sistema operativo: en Windows, es el directorio de trabajo actual del proceso padre, mientras que en Unix es el establecido con setWorkingDirectory().
- Si el nombre del programa es un nombre de archivo simple sin barras, el comportamiento depende del sistema operativo. En sistemas Unix, QProcess buscará en la variable de entorno `
PATH`; en Windows, la búsqueda la realiza el sistema operativo y buscará primero en el directorio actual del proceso padre antes que en la variable de entorno `PATH` (consulte la documentación de `CreateProcess` para ver la lista completa).
Para evitar un comportamiento dependiente de la plataforma o cualquier problema relacionado con la forma en que se ha iniciado la aplicación actual, es recomendable pasar siempre una ruta absoluta al ejecutable que se va a iniciar. Para los binarios auxiliares incluidos con la aplicación, se puede construir dicha ruta comenzando por QCoreApplication::applicationDirPath(). Del mismo modo, para ejecutar explícitamente un ejecutable que se encuentre en una ruta relativa respecto al directorio establecido con setWorkingDirectory(), utilice una ruta al programa que comience por «./» o «../», según sea el caso.
En Windows, el sufijo «.exe» no es necesario en la mayoría de los casos, salvo en los descritos en la documentación de CreateProcess. Además, QProcess convertirá las barras inclinadas de estilo Unix en barras invertidas de ruta de Windows para el nombre del programa. Esto permite que el código que utiliza QProcess se escriba de forma multiplataforma, tal y como se muestra en los ejemplos anteriores.
QProcess no admite la ejecución directa de funciones integradas del shell de Unix o del intérprete de comandos de Windows, como el comando « dir » de cmd.exe o « export » del shell de Bourne. En Unix, aunque muchas funciones integradas del shell también se proporcionan como ejecutables independientes, su comportamiento puede diferir del de las implementadas como funciones integradas. Para ejecutar esos comandos, hay que ejecutar explícitamente el intérprete con las opciones adecuadas. En sistemas Unix, ejecute «/bin/sh» con dos argumentos: «-c» y una cadena con la línea de comandos que se va a ejecutar. En Windows, debido a la forma no estándar en qu cmd.exe a analiza su línea de comandos, utilice setNativeArguments() (por ejemplo, «/c dir d:»).
Variables de entorno
La API de QProcess ofrece métodos para manipular las variables de entorno que verá el proceso hijo. Por defecto, el proceso hijo tendrá una copia de las variables de entorno del proceso actual que existan en el momento en que se llame a la función start(). Esto significa que cualquier modificación realizada mediante qputenv() antes de esa llamada se reflejará en el entorno del proceso hijo. Ten en cuenta que QProcess no intenta evitar las condiciones de carrera con qputenv() que puedan producirse en otros hilos, por lo que se recomienda evitar qputenv() tras el inicio inicial de la aplicación.
El entorno de un proceso hijo específico se puede modificar mediante las funciones processEnvironment() y setProcessEnvironment(), que utilizan la clase QProcessEnvironment. Por defecto, processEnvironment() devolverá un objeto para el que QProcessEnvironment::inheritsFromParent() sea verdadero. Establecer un entorno que no herede del proceso padre hará que QProcess utilice exactamente ese entorno para el proceso hijo cuando se inicie.
El escenario habitual parte del entorno actual llamando a ` QProcessEnvironment::systemEnvironment()` y, a continuación, procede a añadir, modificar o eliminar variables específicas. La lista de variables resultante puede aplicarse entonces a un `QProcess` mediante ` setProcessEnvironment()`.
Es posible eliminar todas las variables del entorno o partir de un entorno vacío utilizando el constructor por defecto de `QProcessEnvironment()`. Esto no es recomendable fuera de condiciones controladas y específicas del sistema, ya que puede haber variables del sistema establecidas en el entorno del proceso actual que sean necesarias para la correcta ejecución del proceso hijo.
En Windows, QProcess copiará las variables de entorno « "PATH" » y « "SystemRoot" » del proceso actual si no están definidas. No es posible desactivarlas por completo, pero sí establecerlas con valores vacíos. Establecer « "PATH" » en vacío en Windows probablemente provocará que el proceso hijo no se inicie.
Comunicación a través de canales
Los procesos disponen de dos canales de salida predefinidos: el canal de salida estándar (stdout) proporciona la salida habitual de la consola, y el canal de error estándar (stderr) suele proporcionar los errores que imprime el proceso. Estos canales representan dos flujos de datos independientes. Se puede alternar entre ellos llamando a ` setReadChannel()`. `QProcess` emite ` readyRead()` cuando hay datos disponibles en el canal de lectura actual. También emite ` readyReadStandardOutput()` cuando hay nuevos datos de salida estándar disponibles, y cuando hay nuevos datos de error estándar disponibles, se emite ` readyReadStandardError()`. En lugar de llamar a read(), readLine() o getChar(), puedes leer explícitamente todos los datos de cualquiera de los dos canales llamando a readAllStandardOutput() o readAllStandardError().
La terminología utilizada para los canales puede resultar engañosa. Hay que tener en cuenta que los canales de salida del proceso se corresponden con los canales de lectura de QProcess, mientras que los canales de entrada del proceso se corresponden con los canales de escritura de QProcess. Esto se debe a que lo que leemos mediante QProcess es la salida del proceso, y lo que escribimos se convierte en la entrada del proceso.
QProcess puede fusionar los dos canales de salida, de modo que tanto los datos de salida estándar como los de error estándar del proceso en ejecución utilicen el canal de salida estándar. Llama a ` setProcessChannelMode()` con ` MergedChannels ` antes de iniciar el proceso para activar esta función. También existe la opción de reenviar la salida del proceso en ejecución al proceso principal que lo ha invocado, pasando ` ForwardedChannels ` como argumento. Asimismo, es posible reenviar solo uno de los canales de salida; normalmente se utilizaría ` ForwardedErrorChannel`, aunque también existe ` ForwardedOutputChannel `. Ten en cuenta que el uso del reenvío de canales suele ser una mala idea en aplicaciones GUI; en su lugar, deberías mostrar los errores gráficamente.
Ciertos procesos necesitan una configuración especial del entorno para funcionar. Puedes establecer variables de entorno para tu proceso llamando a ` setProcessEnvironment()`. Para establecer un directorio de trabajo, llama a ` setWorkingDirectory()`. Por defecto, los procesos se ejecutan en el directorio de trabajo actual del proceso que los invoca.
La posición y el orden Z en pantalla de las ventanas pertenecientes a aplicaciones GUI iniciadas con QProcess están controlados por el sistema de ventanas subyacente. Para las aplicaciones Qt 5, la posición se puede especificar mediante la opción de línea de comandos ` -qwindowgeometry `; las aplicaciones X11 suelen aceptar la opción de línea de comandos ` -geometry `.
API de procesos síncronos
QProcess proporciona un conjunto de funciones que permiten utilizarlo sin un bucle de eventos, suspendiendo el hilo de llamada hasta que se emitan determinadas señales:
- waitForStarted() se bloquea hasta que el proceso se haya iniciado.
- waitForReadyRead() se bloquea hasta que haya nuevos datos disponibles para su lectura en el canal de lectura actual.
- waitForBytesWritten() se bloquea hasta que se haya escrito una carga útil de datos en el proceso.
- waitForFinished() queda en espera hasta que el proceso haya finalizado.
Llamar a estas funciones desde el hilo principal (el hilo que llama a QApplication::exec()) puede provocar que tu interfaz de usuario se cuelgue.
El siguiente ejemplo ejecuta gzip para comprimir la cadena «Qt rocks!», sin un bucle de eventos:
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();Consideraciones de seguridad
Trata el nombre del programa, los argumentos, el entorno y el directorio de trabajo como entradas hostiles siempre que alguno de ellos proceda de una fuente no fiable (la red, un archivo no fiable, una aplicación controlada por otros usuarios). Un proceso iniciado por QProcess se ejecuta con todos los privilegios de la aplicación que lo invoca.
Resolución del nombre del programa
Siempre que sea posible, pasa una ruta absoluta como nombre del programa. Un nombre de archivo simple se resuelve mediante la variable de entorno ` PATH ` en Unix, o según el orden de búsqueda del sistema operativo en Windows (que históricamente incluye el directorio actual, así como ` PATH`), por lo que un atacante que pueda corromper ` PATH ` o colocar un archivo en un directorio de búsqueda puede elegir qué binario se ejecuta. Consulte Finding the Executable para obtener más detalles sobre el proceso de búsqueda de binarios.
Manejo de argumentos
Pase los argumentos como elementos separados de una lista mediante start() o setArguments(); nunca construya una única cadena de comando a partir de partes no fiables. En Unix, los argumentos se envían al proceso hijo tal cual, como entradas individuales de argv sin intervención del shell, por lo que caracteres como &, |, ; o $ no tienen ningún significado especial. En Windows, QProcess encerrá entre comillas y escapará los argumentos de forma adecuada según las reglas establecidas por la función Win32 ` CommandLineToArgvW() `. En ninguno de los dos sistemas operativos QProcess utilizará automáticamente el shell.
Al utilizar splitCommand() y startCommand(), hay que tener en cuenta que sus reglas de tokenización y escape son diferentes de las de los shells de Windows y POSIX. Una entrada con escape incorrecto abre la posibilidad de una inyección de argumentos.
Ejecución de shells y archivos por lotes
En Windows, no pases argumentos no fiables a un archivo por lotes (.bat o .cmd) ni a cmd.exe. Es preferible utilizar setNativeArguments() y encerarlos entre comillas y escapar los caracteres por tu cuenta. QProcess encierra los argumentos según las reglas de CommandLineToArgvW(), pero cmd.exe analiza su línea de comandos de forma diferente y recibe los metacaracteres del shell %, ^, &, |, <, >, ( y ) sin escapar. Por lo tanto, un argumento como args&calc.exe pasado a un script .cmd ejecuta calc.exe como un segundo comando. Ten en cuenta que en Windows todos los argumentos se combinan internamente en una única cadena de línea de comandos, por lo que ni siquiera pasar los argumentos por separado como process.start("file.cmd", {"args", "&calc.exe"}) resuelve el problema. Muchas herramientas instalan scripts por lotes (por ejemplo, los wrappers de npm, yarn o gradle ), por lo que es fácil pasar por alto que el objetivo sea un archivo por lotes.
En Unix, pueden darse problemas similares si se inicia el shell de forma explícita —por ejemplo, process.start("/bin/sh", {"-c", "args&&malicious_binary"}) —; en ese caso, es el shell, y no QProcess, el que analiza la cadena -c y asigna a &&, ;, |, las comillas invertidas y $() su significado habitual, tal y como hace cmd.exe en Windows. En este caso, el &&malicious_binary final ejecuta un segundo programa tras args, por lo que ensamblar esa cadena -c a partir de una entrada no fiable constituye una inyección de comandos.
Véase también QBuffer, QFile y QTcpSocket.
Documentación sobre tipos de miembros
QProcess::CreateProcessArgumentModifier
Nota: Esta definición de tipo solo está disponible en Windows de escritorio.
En Windows, QProcess utiliza la función de la API de Win32 CreateProcess para iniciar procesos hijos. Aunque QProcess ofrece una forma cómoda de iniciar procesos sin tener que preocuparse por los detalles de la plataforma, en algunos casos resulta conveniente ajustar con precisión los parámetros que se pasan a CreateProcess. Esto se consigue definiendo una función CreateProcessArgumentModifier y pasándola a setCreateProcessArgumentsModifier.
Una función ` CreateProcessArgumentModifier ` toma un parámetro: un puntero a una estructura ` CreateProcessArguments `. Los miembros de esta estructura se pasarán a ` CreateProcess ` una vez que se haya llamado a la función ` CreateProcessArgumentModifier `.
El siguiente ejemplo muestra cómo pasar indicadores personalizados a CreateProcess. Al iniciar un proceso de consola B desde un proceso de consola A, QProcess reutilizará, por defecto, la ventana de consola del proceso A para el proceso B. En este ejemplo, en su lugar, se crea una nueva ventana de consola con una combinación de colores personalizada para el proceso hijo 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");Véase también QProcess::CreateProcessArguments y setCreateProcessArgumentsModifier().
enum QProcess::ExitStatus
Esta enumeración describe los diferentes estados de salida de QProcess.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::NormalExit | 0 | El proceso finalizó con normalidad. |
QProcess::CrashExit | 1 | El proceso se ha bloqueado. |
Véase también exitStatus().
enum QProcess::InputChannelMode
Esta enumeración describe los modos de los canales de entrada de proceso de ` QProcess`. Pasa uno de estos valores a ` setInputChannelMode()` para establecer el modo actual del canal de escritura.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::ManagedInputChannel | 0 | QProcess gestiona la entrada del proceso en ejecución. Este es el modo predeterminado del canal de entrada de QProcess. |
QProcess::ForwardedInputChannel | 1 | QProcess Reenvía la entrada del proceso principal al proceso en ejecución. El proceso hijo lee su entrada estándar de la misma fuente que el proceso principal. Ten en cuenta que el proceso principal no debe intentar leer su entrada estándar mientras el proceso hijo esté en ejecución. |
Véase también ` setInputChannelMode()`.
enum QProcess::ProcessChannel
Esta enumeración describe los canales de proceso utilizados por el proceso en ejecución. Pasa uno de estos valores a ` setReadChannel()` para establecer el canal de lectura actual de ` QProcess`.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::StandardOutput | 0 | La salida estándar (stdout) del proceso en ejecución. |
QProcess::StandardError | 1 | La salida de error estándar (stderr) del proceso en ejecución. |
Véase también setReadChannel().
enum QProcess::ProcessChannelMode
Esta enumeración describe los modos de los canales de salida de proceso de QProcess. Se debe pasar uno de estos valores a setProcessChannelMode() para establecer el modo actual del canal de lectura.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::SeparateChannels | 0 | QProcess gestiona la salida del proceso en ejecución, manteniendo los datos de salida estándar y de error estándar en búferes internos separados. Se puede seleccionar el canal de lectura actual de QProcess llamando a setReadChannel(). Este es el modo de canal predeterminado de QProcess. |
QProcess::MergedChannels | 1 | QProcess fusiona la salida del proceso en ejecución en el canal de salida estándar (stdout). El canal de error estándar (stderr) no recibirá ningún dato. Los datos de salida estándar y de error estándar del proceso en ejecución se entrelazan. En el caso de los procesos separados, la salida fusionada del proceso en ejecución se reenvía al proceso principal. |
QProcess::ForwardedChannels | 2 | QProcess reenvía la salida del proceso en ejecución al proceso principal. Todo lo que el proceso hijo escriba en su salida estándar y en su error estándar se escribirá en la salida estándar y en el error estándar del proceso principal. |
QProcess::ForwardedErrorChannel | 4 | QProcess gestiona la salida estándar del proceso en ejecución, pero reenvía su error estándar al proceso principal. Esto refleja el uso habitual de las herramientas de línea de comandos como filtros, en las que la salida estándar se redirige a otro proceso o a un archivo, mientras que el error estándar se muestra en la consola con fines de diagnóstico. (Este valor se introdujo en Qt 5.2.) |
QProcess::ForwardedOutputChannel | 3 | Complementario a ForwardedErrorChannel. (Este valor se introdujo en Qt 5.2.) Nota: Windows suprime intencionadamente la salida de las aplicaciones exclusivamente de interfaz gráfica de usuario (GUI) hacia las consolas heredadas. Esto no se aplica a la salida redirigida a archivos o tuberías. Para reenviar, no obstante, la salida de las aplicaciones exclusivamente de interfaz gráfica de usuario a la consola, debe utilizar SeparateChannels y realizar el reenvío usted mismo leyendo la salida y escribiéndola en los canales de salida adecuados. |
Véase también setProcessChannelMode().
enum QProcess::ProcessError
Esta enumeración describe los diferentes tipos de errores que notifica QProcess.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::FailedToStart | 0 | El proceso no se ha podido iniciar. O bien falta el programa invocado, o bien es posible que no dispongas de los permisos o recursos suficientes para ejecutarlo. |
QProcess::Crashed | 1 | El proceso se ha bloqueado poco después de iniciarse correctamente. |
QProcess::Timedout | 2 | La última función waitFor...() ha agotado el tiempo de espera. El estado de QProcess no ha cambiado, por lo que puede intentar volver a llamar a waitFor...(). |
QProcess::WriteError | 4 | Se ha producido un error al intentar escribir en el proceso. Por ejemplo, es posible que el proceso no se esté ejecutando o que haya cerrado su canal de entrada. |
QProcess::ReadError | 3 | Se ha producido un error al intentar leer del proceso. Por ejemplo, es posible que el proceso no se esté ejecutando. |
QProcess::UnknownError | 5 | Se ha producido un error desconocido. Este es el valor de retorno predeterminado de error(). |
Véase también error().
enum QProcess::ProcessState
Esta enumeración describe los diferentes estados de QProcess.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::NotRunning | 0 | El proceso no se está ejecutando. |
QProcess::Starting | 1 | El proceso se está iniciando, pero el programa aún no se ha ejecutado. |
QProcess::Running | 2 | El proceso se está ejecutando y está listo para leer y escribir. |
Véase también state().
[since 6.6] enum class QProcess::UnixProcessFlag
flags QProcess::UnixProcessFlags
Estas opciones se pueden utilizar en el campo « flags » (Opciones de configuración) de UnixProcessParameters.
| Constante | Valor | Descripción |
|---|---|---|
QProcess::UnixProcessFlag::CloseFileDescriptors | 0x0010 | Cierra todos los descriptores de archivo por encima del umbral definido por lowestFileDescriptorToClose, evitando que cualquier descriptor actualmente abierto en el proceso padre se filtre accidentalmente al proceso hijo. Los descriptores de archivo stdin, stdout y stderr nunca se cierran. |
QProcess::UnixProcessFlag::CreateNewSession (since Qt 6.7) | 0x0040 | Inicia una nueva sesión de proceso llamando a ` setsid(2)`. Esto permite que el proceso hijo sobreviva a la sesión en la que se encuentra el proceso actual. Este es uno de los pasos que realiza ` startDetached()` para permitir que el proceso se separe, y también es uno de los pasos para convertir un proceso en daemon. |
QProcess::UnixProcessFlag::DisconnectControllingTerminal (since Qt 6.7) | 0x0080 | Solicita que el proceso se desconecte de su terminal de control, si dispone de uno. Si no tiene ninguno, no ocurre nada. Los procesos que sigan conectados a un terminal de control pueden recibir una señal de «colgar» (SIGHUP) si el terminal se cierra, o alguna de las otras señales de control del terminal (SIGTSTP, SIGTTIN, SIGTTOU). Ten en cuenta que, en algunos sistemas operativos, un proceso solo puede desconectarse del terminal de control si es el líder de la sesión, lo que significa que puede ser necesario el indicador « CreateNewSession ». Al igual que este, este es uno de los pasos para convertir un proceso en un demonio. |
QProcess::UnixProcessFlag::IgnoreSigPipe | 0x0002 | Establece siempre la señal « SIGPIPE » como ignorada (SIG_IGN), incluso si se ha activado la bandera ResetSignalHandlers. Por defecto, si el proceso hijo intenta escribir en su salida estándar o en su error estándar después de que el canal correspondiente se haya cerrado con QProcess::closeReadChannel(), recibiría la señal « SIGPIPE » y terminaría inmediatamente; con esta bandera, la operación de escritura falla sin que se emita ninguna señal y el proceso hijo puede continuar ejecutándose. |
QProcess::UnixProcessFlag::ResetIds (since Qt 6.7) | 0x0100 | Elimina cualquier ID de usuario o de grupo efectivo retenido que el proceso actual pueda tener aún (véase setuid(2) y setgid(2), además de QCoreApplication::setSetuidAllowed()). Esto resulta útil si el proceso actual tenía setuid o setgid y no se desea que el proceso hijo conserve los privilegios elevados. |
QProcess::UnixProcessFlag::ResetSignalHandlers | 0x0001 | Restablece todos los controladores de señales de Unix a su estado predeterminado (es decir, pasa SIG_DFL a signal(2)). Esta bandera es útil para garantizar que cualquier señal ignorada (SIG_IGN) no afecte al comportamiento del proceso hijo. |
QProcess::UnixProcessFlag::UseVFork | 0x0020 | Solicita que QProcess utilice vfork(2) para iniciar el proceso hijo. Utilice esta bandera para indicar que la función de devolución de llamada establecida con setChildProcessModifier() es segura de ejecutar en el lado del proceso hijo de un vfork(2); es decir, que la función de devolución de llamada no modifica ninguna variable no local (ni directamente ni a través de ninguna función que llame), ni intenta comunicarse con el proceso padre. Depende de la implementación si ` QProcess ` utilizará realmente ` vfork(2) ` y si ` vfork(2) ` es diferente del ` fork(2)` estándar. |
QProcess::UnixProcessFlag::DisableCoreDumps (since Qt 6.9) | 0x0200 | Solicita que QProcess desactive los volcados de memoria (core dumps) en el proceso hijo. Esto resulta útil si es probable que el ejecutable en ejecución sufra un fallo, pero los usuarios y los responsables del mantenimiento no están interesados en generar informes de errores para esas condiciones (por ejemplo, si el ejecutable es un proceso de prueba). Esta configuración no afecta a la función ` exitStatus()` del proceso que se ha bloqueado. Se implementa estableciendo en cero el límite blando del recurso de tamaño del volcado de memoria, lo que significa que la aplicación aún puede revertir este cambio aumentándolo hasta un valor igual al límite duro. |
Esta enumeración se introdujo en Qt 6.6.
El tipo `UnixProcessFlags` es un `typedef` para ` QFlags<UnixProcessFlag>`. Almacena una combinación OR de valores de `UnixProcessFlag`.
Véase también setUnixProcessParameters() y unixProcessParameters().
Documentación de las funciones miembro
[explicit] QProcess::QProcess(QObject *parent = nullptr)
Crea un objeto `QProcess` con el ` parent` indicado.
[virtual noexcept] QProcess::~QProcess()
Destruye el objeto ` QProcess `, es decir, finaliza el proceso.
Ten en cuenta que esta función no devolverá ningún valor hasta que el proceso haya finalizado.
QStringList QProcess::arguments() const
Devuelve los argumentos de la línea de comandos con los que se inició el proceso por última vez.
Véase también setArguments() y start().
[override virtual] qint64 QProcess::bytesToWrite() const
Reimplementa: ` QIODevice::bytesToWrite()` const.
[since 6.0] std::function<void ()> QProcess::childProcessModifier() const
Devuelve la función modificadora establecida previamente mediante la llamada a ` setChildProcessModifier()`.
Nota: Esta función solo está disponible en plataformas Unix.
Esta función se introdujo en Qt 6.0.
Véanse también « setChildProcessModifier()» y « unixProcessParameters()».
[override virtual] void QProcess::close()
Reimplementa: QIODevice::close().
Cierra toda comunicación con el proceso y lo termina. Tras llamar a esta función, QProcess ya no emitirá readyRead(), y ya no se podrán leer ni escribir datos.
void QProcess::closeReadChannel(QProcess::ProcessChannel channel)
Cierra el canal de lectura channel. Tras llamar a esta función, QProcess dejará de recibir datos en dicho canal. Los datos que ya se hayan recibido seguirán estando disponibles para su lectura.
Llama a esta función para ahorrar memoria, si no te interesa la salida del proceso.
Véase también closeWriteChannel() y setReadChannel().
void QProcess::closeWriteChannel()
Programa el cierre del canal de escritura de QProcess. El canal se cerrará una vez que se hayan escrito todos los datos en el proceso. Tras llamar a esta función, cualquier intento de escribir en el proceso fallará.
El cierre del canal de escritura es necesario para los programas que leen datos de entrada hasta que se haya cerrado el canal. Por ejemplo, el programa «more» se utiliza para mostrar datos de texto en una consola tanto en Unix como en Windows. Sin embargo, no mostrará los datos de texto hasta que se haya cerrado el canal de escritura de ` QProcess`. Ejemplo:
QProcess more;
more.start("more");
more.write("Text to display");
more.closeWriteChannel();
// QProcess will emit readyRead() once "more" starts printingEl canal de escritura se abre implícitamente al llamar a start().
Véase también closeReadChannel().
QProcess::CreateProcessArgumentModifier QProcess::createProcessArgumentsModifier() const
Devuelve una función modificadora de « CreateProcess » previamente definida.
Nota: Esta función solo está disponible en la plataforma Windows.
Véase también setCreateProcessArgumentsModifier() y QProcess::CreateProcessArgumentModifier.
QProcess::ProcessError QProcess::error() const
Devuelve el tipo de error que se ha producido en última instancia.
Véase también state().
[signal] void QProcess::errorOccurred(QProcess::ProcessError error)
Esta señal se emite cuando se produce un error en el proceso. El código de error ( error ) especificado describe el tipo de error que se ha producido.
[static] int QProcess::execute(const QString &program, const QStringList &arguments = {})
Inicia el programa program con los argumentos arguments en un nuevo proceso, espera a que finalice y, a continuación, devuelve el código de salida del proceso. Cualquier dato que el nuevo proceso escriba en la consola se reenvía al proceso que lo ha llamado.
El entorno y el directorio de trabajo se heredan del proceso que realiza la llamada.
El manejo de argumentos es idéntico al de la sobrecarga correspondiente de start().
Si no se puede iniciar el proceso, se devuelve -2. Si el proceso se bloquea, se devuelve -1. En caso contrario, se devuelve el código de salida del proceso.
Véase también start().
int QProcess::exitCode() const
Devuelve el código de salida del último proceso que ha finalizado.
Este valor no es válido a menos que exitStatus() devuelva NormalExit.
QProcess::ExitStatus QProcess::exitStatus() const
Devuelve el código de salida del último proceso que ha finalizado.
En Windows, si el proceso se ha terminado mediante la función `TerminateProcess()` desde otra aplicación, esta función seguirá devolviendo ` NormalExit `, a menos que el código de salida sea inferior a 0.
[noexcept, since 6.7] void QProcess::failChildProcessModifier(const char *description, int error = 0)
Estas funciones pueden utilizarse dentro del conjunto de modificadores con ` setChildProcessModifier()` para indicar que se ha producido una condición de error. Cuando el modificador llama a estas funciones, ` QProcess ` emitirá ` errorOccurred()` con el código ` QProcess::FailedToStart ` en el proceso padre. La función « description » puede utilizarse para incluir información en « errorString()» que ayude a diagnosticar el problema, normalmente el nombre de la llamada que ha fallado, de forma similar a la función de la biblioteca C « perror() ». Además, el parámetro « error » puede ser un código de error « <errno.h> », cuyo texto también se incluirá.
Por ejemplo, un modificador secundario podría preparar un descriptor de archivo adicional para el proceso secundario de esta manera:
process.setChildProcessModifier([fd, &process]() {
if (dup2(fd, TargetFileDescriptor) < 0)
process.failChildProcessModifier(errno, "aux comm channel");
});
process.start();Donde ` fd ` es un descriptor de archivo actualmente abierto en el proceso padre. Si la llamada al sistema ` dup2() ` diera lugar a una condición ` EBADF `, el proceso ` errorString()` podría ser «El modificador del proceso hijo ha notificado un error: canal de comunicación auxiliar: descriptor de archivo incorrecto».
Esta función no devuelve el control al llamante. Su uso en cualquier otro lugar que no sea el modificador hijo y con el objeto QProcess correcto da lugar a un comportamiento indefinido.
Nota: La implementación impone un límite de longitud al parámetro description de unos 500 caracteres. Esto no incluye el texto del código error.
Esta función se introdujo en Qt 6.7.
Véase también setChildProcessModifier() y setUnixProcessParameters().
[signal] void QProcess::finished(int exitCode, QProcess::ExitStatus exitStatus = NormalExit)
Esta señal se emite cuando el proceso finaliza. exitCode es el código de salida del proceso (válido únicamente para salidas normales), y exitStatus es el estado de salida. Una vez finalizado el proceso, los búferes de QProcess siguen intactos. Todavía es posible leer cualquier dato que el proceso haya podido escribir antes de finalizar.
Véase también exitStatus().
QProcess::InputChannelMode QProcess::inputChannelMode() const
Devuelve el modo del canal de entrada estándar de QProcess.
Véase también setInputChannelMode() y InputChannelMode.
[override virtual] bool QProcess::isSequential() const
Reimplementa: ` QIODevice::isSequential()` const.
[slot] void QProcess::kill()
Termina el proceso actual, lo que provoca que se cierre de inmediato.
En Windows, kill() utiliza TerminateProcess, y en Unix y macOS, se envía la señal SIGKILL al proceso.
Véase también terminate().
QString QProcess::nativeArguments() const
Devuelve los argumentos adicionales de la línea de comandos nativos del programa.
Nota: Esta función solo está disponible en la plataforma Windows.
Véase también setNativeArguments().
[static] QString QProcess::nullDevice()
El dispositivo nulo del sistema operativo.
La ruta de archivo devuelta utiliza separadores de directorios nativos.
Véase también QProcess::setStandardInputFile(), QProcess::setStandardOutputFile() y QProcess::setStandardErrorFile().
[override virtual] bool QProcess::open(QIODeviceBase::OpenMode mode = ReadWrite)
Reimplementa: QIODevice::open(modo OpenMode de QIODeviceBase).
Inicia el programa establecido mediante setProgram() con los argumentos definidos mediante setArguments(). El OpenMode se establece en mode.
Este método es un alias de start() y solo existe para implementar completamente la interfaz definida por QIODevice.
Devuelve ` true ` si el programa se ha iniciado.
Véanse también start(), setProgram() y setArguments().
QProcess::ProcessChannelMode QProcess::processChannelMode() const
Devuelve el modo de los canales de salida estándar y de error estándar de QProcess.
Véase también setProcessChannelMode(), ProcessChannelMode y setReadChannel().
QProcessEnvironment QProcess::processEnvironment() const
Devuelve el entorno que QProcess pasará a su proceso hijo. Si no se ha configurado ningún entorno mediante setProcessEnvironment(), este método devuelve un objeto que indica que el entorno se heredará del proceso padre.
Véase también setProcessEnvironment(), QProcessEnvironment::inheritsFromParent() y Environment variables.
qint64 QProcess::processId() const
Devuelve el identificador nativo del proceso en ejecución, si está disponible. Si no hay ningún proceso en ejecución en ese momento, se devuelve « 0 ».
QString QProcess::program() const
Devuelve el programa con el que se inició por última vez el proceso.
Véase también setProgram() y start().
QByteArray QProcess::readAllStandardError()
Independientemente del canal de lectura actual, esta función devuelve todos los datos disponibles en la salida de error estándar del proceso como un objeto ` QByteArray`.
Véanse también readyReadStandardError(), readAllStandardOutput(), readChannel() y setReadChannel().
QByteArray QProcess::readAllStandardOutput()
Independientemente del canal de lectura actual, esta función devuelve todos los datos disponibles en la salida estándar del proceso como un objeto ` QByteArray`.
Véanse también readyReadStandardOutput(), readAllStandardError(), readChannel() y setReadChannel().
QProcess::ProcessChannel QProcess::readChannel() const
Devuelve el canal de lectura actual del objeto ` QProcess`.
Véase también setReadChannel().
[override virtual protected] qint64 QProcess::readData(char *data, qint64 maxlen)
Reimplementa: QIODevice::readData(char *data, qint64 maxSize).
[private signal] void QProcess::readyReadStandardError()
Esta señal se emite cuando el proceso ha puesto a disposición nuevos datos a través de su canal de error estándar (stderr). Se emite independientemente del valor actual de ` read channel`.
Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.
Véase también readAllStandardError() y readChannel().
[private signal] void QProcess::readyReadStandardOutput()
Esta señal se emite cuando el proceso ha puesto a disposición nuevos datos a través de su canal de salida estándar (stdout). Se emite independientemente del valor actual de read channel.
Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.
Véase también readAllStandardOutput() y readChannel().
void QProcess::setArguments(const QStringList &arguments)
Establece el « arguments » que se pasará al programa llamado al iniciar el proceso. Esta función debe llamarse antes de « start()».
Véase también start(), setProgram() y arguments().
[since 6.0] void QProcess::setChildProcessModifier(const std::function<void ()> &modifier)
Establece la función « modifier » para el proceso hijo, en sistemas Unix (incluido macOS; para Windows, véase setCreateProcessArgumentsModifier()). La función contenida en el argumento « modifier » se invocará en el proceso hijo una vez que se hayan completado « fork() » o « vfork() » y « QProcess » haya configurado los descriptores de archivo estándar para el proceso hijo, pero antes de « execve() », dentro de « start()».
A continuación se muestra un ejemplo de cómo configurar un proceso hijo para que se ejecute sin privilegios:
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();
}Si la función modificadora se encuentra con una condición de fallo, puede utilizar failChildProcessModifier() para informar de la situación al llamante de QProcess. Alternativamente, puede utilizar otros métodos para detener el proceso, como _exit() o abort().
Ciertas propiedades del proceso hijo, como el cierre de todos los descriptores de archivo superfluos o la desconexión del TTY de control, pueden lograrse más fácilmente utilizando setUnixProcessParameters(), que puede detectar fallos e informar de una condición FailedToStart. El modificador resulta útil para cambiar ciertas propiedades poco habituales del proceso hijo, como la configuración de descriptores de archivo adicionales. Si se establecen tanto un modificador de proceso hijo como parámetros de proceso de Unix, el modificador se ejecuta antes de que se apliquen dichos parámetros.
Nota: En aplicaciones multihilo, esta función debe tener cuidado de no llamar a ninguna función que pueda bloquear mutexes que puedan estar en uso en otros hilos (en general, se recomienda utilizar únicamente funciones definidas por POSIX como «async-signal-safe»). La mayor parte de la API de Qt no es segura dentro de esta función de devolución de llamada, incluidas las funciones ` qDebug()`, y puede provocar interbloqueos.
Nota: Si se establece el indicador UnixProcessParameters::UseVFork mediante setUnixProcessParameters(), QProcess puede utilizar la semántica de vfork() para iniciar el proceso hijo, por lo que esta función debe cumplir restricciones aún más estrictas. En primer lugar, dado que sigue compartiendo memoria con el proceso padre, no debe escribir en ninguna variable no local y debe respetar la semántica de ordenación adecuada al leerlas, para evitar conflictos de datos. En segundo lugar, es posible que aún más funciones de la biblioteca se comporten de forma incorrecta; por lo tanto, esta función solo debe utilizar llamadas al sistema de bajo nivel, como read(), write(), setsid(), nice() y similares.
Esta función se introdujo en Qt 6.0.
Véanse también childProcessModifier(), failChildProcessModifier() y setUnixProcessParameters().
void QProcess::setCreateProcessArgumentsModifier(QProcess::CreateProcessArgumentModifier modifier)
Establece el valor « modifier » para la llamada a la API Win32 « CreateProcess ». Pasa « QProcess::CreateProcessArgumentModifier() » para eliminar un valor establecido anteriormente.
Nota: Esta función solo está disponible en la plataforma Windows y requiere C++11.
Véase también createProcessArgumentsModifier(), QProcess::CreateProcessArgumentModifier y setChildProcessModifier().
void QProcess::setInputChannelMode(QProcess::InputChannelMode mode)
Establece el modo del canal de entrada estándar de QProcess en el valor especificado en mode. Este modo se utilizará la próxima vez que se llame a start().
Véase también inputChannelMode() y InputChannelMode.
void QProcess::setNativeArguments(const QString &arguments)
Establece una « arguments » adicional de la línea de comandos nativa para el programa.
En los sistemas operativos en los que la API del sistema para pasar arguments es de la línea de comandos a un subproceso utiliza de forma nativa una única cadena, es posible que existan líneas de comandos que no puedan pasarse a través de la API portátil basada en listas de QProcess. En tales casos, debe utilizarse esta función para establecer una cadena que se añada a la cadena compuesta a partir de la lista de argumentos habitual, separada por un espacio.
Nota: Esta función solo está disponible en la plataforma Windows.
Véase también nativeArguments().
void QProcess::setProcessChannelMode(QProcess::ProcessChannelMode mode)
Establece el modo de los canales de salida estándar y de error estándar de QProcess en el valor especificado mode. Este modo se utilizará la próxima vez que se llame a start(). Por ejemplo:
QProcess builder;
builder.setProcessChannelMode(QProcess::MergedChannels);
builder.start("make", QStringList() << "-j2");
if (!builder.waitForFinished())
qDebug() << "Make failed:" << builder.errorString();
sino
qDebug() << "Make output:" << builder.readAll();Véase también processChannelMode(), ProcessChannelMode y setReadChannel().
void QProcess::setProcessEnvironment(const QProcessEnvironment &environment)
Establece la variable de entorno ` environment ` que ` QProcess ` pasará al proceso hijo.
Por ejemplo, el siguiente código añade la variable de entorno TMPDIR:
QProcess process;
QProcessEnvironment env = QProcessEnvironment::systemEnvironment();
env.insert("TMPDIR", "C:\\MyApp\\temp"); // Add an environment variable
process.setProcessEnvironment(env);
process.start("myapp");Ten en cuenta que, en Windows, los nombres de las variables de entorno no distinguen entre mayúsculas y minúsculas.
Véase también processEnvironment(), QProcessEnvironment::systemEnvironment() y Environment variables.
[protected] void QProcess::setProcessState(QProcess::ProcessState state)
Establece el estado actual de la clase « QProcess » en el valor « state » especificado.
Véase también state().
void QProcess::setProgram(const QString &program)
Establece el archivo « program » que se utilizará al iniciar el proceso. Esta función debe llamarse antes de « start()».
Si program es una ruta absoluta, especifica el ejecutable exacto que se iniciará. Las rutas relativas se resolverán según las características de cada plataforma, lo que incluye la búsqueda en la variable de entorno PATH (consulta Finding the Executable para obtener más detalles).
Véanse también start(), setArguments(), program() y QStandardPaths::findExecutable().
void QProcess::setReadChannel(QProcess::ProcessChannel channel)
Establece el canal de lectura actual del « QProcess » en el valor indicado « channel ». El canal de entrada actual es el que utilizan las funciones « read()», « readAll()», « readLine()» y « getChar()». Además, determina qué canal activa la función « QProcess » para que emita « readyRead()».
Véase también readChannel().
void QProcess::setStandardErrorFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)
Redirige el error estándar del proceso al archivo fileName. Cuando la redirección está activa, se cierra el canal de lectura de error estándar: intentar leer de él mediante read() siempre dará error, al igual que readAllStandardError(). El archivo se irá completando si mode es «Append»; de lo contrario, se truncará.
Consulte setStandardOutputFile() para obtener más información sobre cómo se abre el archivo.
Nota: si se ha llamado a setProcessChannelMode() con el argumento QProcess::MergedChannels, esta función no tiene ningún efecto.
Véase también setStandardInputFile(), setStandardOutputFile() y setStandardOutputProcess().
void QProcess::setStandardInputFile(const QString &fileName)
Redirige la entrada estándar del proceso al archivo indicado por ` fileName`. Cuando hay una redirección de entrada activa, el objeto ` QProcess ` estará en modo de solo lectura (la llamada a ` write()` provocará un error).
Para que el proceso lea el EOF de inmediato, pasa nullDevice() aquí. Esto es más limpio que utilizar closeWriteChannel() antes de escribir ningún dato, ya que se puede configurar antes de iniciar el proceso.
Si el archivo fileName no existe en el momento en que se llama a start() o no es legible, el inicio del proceso fallará.
Llamar a `setStandardInputFile()` una vez iniciado el proceso no tiene ningún efecto.
Véanse también setStandardOutputFile(), setStandardErrorFile() y setStandardOutputProcess().
void QProcess::setStandardOutputFile(const QString &fileName, QIODeviceBase::OpenMode mode = Truncate)
Redirige la salida estándar del proceso al archivo fileName. Cuando la redirección está activa, se cierra el canal de lectura de la salida estándar: intentar leer de él mediante read() siempre dará error, al igual que readAllStandardOutput().
Para descartar toda la salida estándar del proceso, pasa aquí nullDevice(). Esto es más eficiente que simplemente no leer nunca la salida estándar, ya que no se llenan los búferes de QProcess.
Si el archivo fileName no existe en el momento en que se llama a start(), se creará. Si no se puede crear, la ejecución fallará.
Si el archivo existe y mode es QIODeviceBase::Truncate, el archivo se truncará. En caso contrario (si mode es QIODeviceBase::Append), se añadirán datos al final del archivo.
Llamar a setStandardOutputFile() una vez iniciado el proceso no tiene ningún efecto.
Si fileName es una cadena vacía, se detiene la redirección de la salida estándar. Esto resulta útil para restablecer la salida estándar tras una redirección.
Véanse también setStandardInputFile(), setStandardErrorFile() y setStandardOutputProcess().
void QProcess::setStandardOutputProcess(QProcess *destination)
Desvía el flujo de salida estándar de este proceso hacia la entrada estándar del proceso « destination ».
El siguiente comando de shell:
command1 | command2se puede llevar a cabo con QProcess mediante el siguiente código:
QProcess process1;
QProcess process2;
process1.setStandardOutputProcess(&process2);
process1.start("command1");
process2.start("command2");[since 6.6] void QProcess::setUnixProcessParameters(const QProcess::UnixProcessParameters ¶ms)
Establece la params, como configuración y parámetros adicionales para el proceso hijo en sistemas Unix. Esta función se puede utilizar para solicitar a QProcess que modifique el proceso hijo antes de ejecutar el ejecutable de destino.
Esta función se puede utilizar para cambiar ciertas propiedades del proceso hijo, como cerrar todos los descriptores de archivo superfluos, cambiar el nivel de prioridad del proceso hijo o desconectarlo del TTY de control. Para un control más detallado del proceso hijo o para modificarlo de otras formas, utilice la función setChildProcessModifier(). Si se establecen tanto un modificador del proceso hijo como parámetros del proceso de Unix, el modificador se ejecuta antes de que se apliquen dichos parámetros.
Nota: Esta función solo está disponible en plataformas Unix.
Esta función se introdujo en Qt 6.6.
Véase también unixProcessParameters() y setChildProcessModifier().
[since 6.6] void QProcess::setUnixProcessParameters(QProcess::UnixProcessFlags flagsOnly)
Establece la configuración adicional para el proceso hijo en sistemas Unix en ` flagsOnly`. Esto equivale a la sobrecarga en la que solo se establece el campo ` flags `.
Nota: Esta función solo está disponible en plataformas Unix.
Se trata de una función sobrecargada.
Esta función se introdujo en Qt 6.6.
Véase también ` unixProcessParameters()` y ` setChildProcessModifier()`.
void QProcess::setWorkingDirectory(const QString &dir)
Establece el directorio de trabajo en dir. QProcess iniciará el proceso en este directorio. El comportamiento predeterminado es iniciar el proceso en el directorio de trabajo del proceso que lo invoca.
Véase también workingDirectory() y start().
[static] QStringList QProcess::splitCommand(QStringView command)
Divide la cadena « command » en una lista de tokens y devuelve dicha lista.
Los tokens que contengan espacios pueden ir entre comillas dobles; tres comillas dobles consecutivas representan el propio carácter de comilla.
void QProcess::start(const QString &program, const QStringList &arguments = {}, QIODeviceBase::OpenMode mode = ReadWrite)
Inicia el objeto ` program ` especificado en un nuevo proceso, pasando los argumentos de la línea de comandos de ` arguments`. Consulta ` setProgram()` para obtener información sobre cómo ` QProcess ` busca el ejecutable que se va a ejecutar. El `OpenMode` se establece en ` mode`. No se realiza ninguna división adicional de los argumentos.
El objeto ` QProcess ` pasará inmediatamente al estado «Starting». Si el proceso se inicia correctamente, ` QProcess ` emitirá ` started()`; de lo contrario, se emitirá ` errorOccurred()`. Tenga en cuenta que, en las plataformas capaces de iniciar procesos hijos de forma sincrónica (en particular, Windows), dichas señales se emitirán antes de que esta función devuelva un valor y este objeto ` QProcess ` pasará al estado « QProcess::Running » o « QProcess::NotRunning », respectivamente. En otras plataformas, las señales « started » () y « errorOccurred » () se retrasarán.
Llama a waitForStarted() para asegurarte de que el proceso se ha iniciado (o no se ha podido iniciar) y de que se han emitido esas señales. Es seguro llamar a esa función incluso si ya se conoce el estado de inicio del proceso, aunque la señal no se volverá a emitir.
Windows: Los argumentos se encierran entre comillas y se unen en una línea de comandos compatible con la función de Windows ` CommandLineToArgvW() `. Para programas que tengan requisitos de comillas en la línea de comandos diferentes, es necesario utilizar ` setNativeArguments`(). Un programa destacado que no sigue las reglas de ` CommandLineToArgvW() ` es `cmd.exe` y, por consiguiente, todos los scripts por lotes.
Si el objeto ` QProcess ` ya está ejecutando un proceso, es posible que se muestre una advertencia en la consola, y el proceso existente seguirá ejecutándose sin verse afectado.
Nota: El éxito al iniciar el proceso hijo solo implica que el sistema operativo ha creado correctamente el proceso y le ha asignado los recursos que tiene todo proceso, como su ID de proceso. El proceso hijo puede bloquearse o fallar de algún otro modo muy pronto y, por lo tanto, no producir la salida esperada. En la mayoría de los sistemas operativos, esto puede incluir errores de enlace dinámico.
Véanse también processId(), started(), waitForStarted() y setNativeArguments().
void QProcess::start(QIODeviceBase::OpenMode mode = ReadWrite)
Inicia el programa establecido mediante ` setProgram()` con los argumentos definidos en ` setArguments()`. El `OpenMode` se establece en ` mode`.
Esta es una función sobrecargada.
Véanse también open(), setProgram() y setArguments().
[since 6.0] void QProcess::startCommand(const QString &command, QIODeviceBase::OpenMode mode = ReadWrite)
Ejecuta el comando « command » en un nuevo proceso. El parámetro «OpenMode» se establece en « mode ».
command es una única cadena de texto que contiene tanto el nombre del programa como sus argumentos. Los argumentos están separados por uno o más espacios. Por ejemplo:
QProcess process;
process.startCommand("del /s *.txt");
// same as process.start("del", QStringList() << "/s" << "*.txt");
//...Los argumentos que contengan espacios deben ir entre comillas para que se pasen correctamente al nuevo proceso. Por ejemplo:
QProcess process;
process.startCommand("dir \"My Documents\"");Las comillas literales en la cadena « command » se representan mediante comillas triples. Por ejemplo:
QProcess process;
process.startCommand("dir \"Epic 12\"\"\" Singles\"");Una vez que la cadena « command » se ha dividido y se han eliminado las comillas, esta función se comporta como « start()».
En sistemas operativos en los que la API del sistema para pasar argumentos de línea de comandos a un subproceso utiliza de forma nativa una única cadena (Windows), es posible concebir líneas de comandos que no puedan pasarse a través de la API portátil basada en listas de QProcess. En estos casos excepcionales, es necesario utilizar setProgram() y setNativeArguments() en lugar de esta función.
Esta función se introdujo en Qt 6.0.
Véanse también splitCommand() y start().
bool QProcess::startDetached(qint64 *pid = nullptr)
Inicia el programa establecido mediante ` setProgram()` con los argumentos definidos en ` setArguments()` en un nuevo proceso y se desvincula de él. Devuelve ` true ` si la operación se realiza correctamente; en caso contrario, devuelve ` false`. Si el proceso que realiza la llamada finaliza, el proceso desvinculado seguirá ejecutándose sin verse afectado.
Unix: El proceso iniciado se ejecutará en su propia sesión y actuará como un demonio.
El proceso se iniciará en el directorio establecido por setWorkingDirectory(). Si workingDirectory() está vacío, el directorio de trabajo se hereda del proceso que realiza la llamada.
Si la función se ejecuta correctamente, *pid se establece en el identificador de proceso del proceso iniciado; en caso contrario, se establece en -1. Ten en cuenta que el proceso hijo puede salir y que el PID puede dejar de ser válido sin previo aviso. Además, una vez que el proceso hijo sale, el mismo PID puede ser reutilizado y utilizado por un proceso completamente diferente. El código de usuario debe tener cuidado al utilizar esta variable, especialmente si se pretende terminar el proceso de forma forzada mediante los medios del sistema operativo.
startDetached() solo admite los siguientes setters de propiedades:
- setArguments()
- setCreateProcessArgumentsModifier()
- setNativeArguments()
- setProcessEnvironment()
- setProgram()
- setStandardErrorFile()
- setStandardInputFile()
- setStandardOutputFile()
- setProcessChannelMode(QProcess::MergedChannels)
- setStandardOutputProcess()
- setWorkingDirectory()
Se ignoran todas las demás propiedades del objeto ` QProcess `.
Nota: El proceso invocado hereda la ventana de consola del proceso que lo invoca. Para suprimir la salida de la consola, redirige la salida estándar y de error a ` QProcess::nullDevice()`.
Véase también start() y 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)
Inicia el programa program con los argumentos arguments en un nuevo proceso y se desvincula de él. Devuelve true si se realiza correctamente; en caso contrario, devuelve false. Si el proceso que realiza la llamada finaliza, el proceso desvinculado seguirá ejecutándose sin verse afectado.
El manejo de argumentos es idéntico al de la sobrecarga correspondiente de ` start()`.
El proceso se iniciará en el directorio workingDirectory. Si workingDirectory está vacío, el directorio de trabajo se hereda del proceso que realiza la llamada.
Si la función se ejecuta correctamente, se asigna a *pid el identificador del proceso iniciado.
Esta función sobrecarga QProcess::startDetached().
Véase también start().
[private signal] void QProcess::started()
Esta señal la emite QProcess cuando el proceso se ha iniciado, y state() devuelve Running.
Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.
QProcess::ProcessState QProcess::state() const
Devuelve el estado actual del proceso.
Véase también stateChanged() y error().
[private signal] void QProcess::stateChanged(QProcess::ProcessState newState)
Esta señal se emite cada vez que cambia el estado de QProcess. El argumento newState indica el estado al que ha cambiado QProcess.
Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.
[static] QStringList QProcess::systemEnvironment()
Devuelve el entorno del proceso que realiza la llamada como una lista de pares clave=valor. Ejemplo:
QStringList environment = QProcess::systemEnvironment();
// environment = {"PATH=/usr/bin:/usr/local/bin",
// "USER=greg", "HOME=/home/greg"}Esta función no almacena en caché el entorno del sistema. Por lo tanto, es posible obtener una versión actualizada del entorno si se han llamado funciones de bajo nivel de la biblioteca C, como setenv o putenv.
Sin embargo, hay que tener en cuenta que las llamadas repetidas a esta función volverán a crear la lista de variables de entorno, lo cual es una operación que no es trivial.
Nota: Para el código nuevo, se recomienda utilizar QProcessEnvironment::systemEnvironment()
Véase también QProcessEnvironment::systemEnvironment() y setProcessEnvironment().
[slot] void QProcess::terminate()
Intenta finalizar el proceso.
Es posible que el proceso no se cierre como resultado de la llamada a esta función (se le da la oportunidad de preguntar al usuario por cualquier archivo sin guardar, etc.).
En Windows, `terminate()` envía un mensaje `WM_CLOSE` a todas las ventanas de nivel superior del proceso y, a continuación, al hilo principal del propio proceso. En Unix y macOS se envía la señal ` SIGTERM `.
Las aplicaciones de consola en Windows que no ejecutan un bucle de eventos, o cuyo bucle de eventos no gestiona el mensaje WM_CLOSE, solo pueden terminarse llamando a kill().
Véase también kill().
[noexcept, since 6.6] QProcess::UnixProcessParameters QProcess::unixProcessParameters() const
Devuelve el objeto ` UnixProcessParameters ` que describe los indicadores y ajustes adicionales que se aplicarán al proceso hijo en sistemas Unix. La configuración por defecto corresponde a un objeto ` UnixProcessParameters` creado de forma predeterminada.
Nota: Esta función solo está disponible en plataformas Unix.
Esta función se introdujo en Qt 6.6.
Véase también setUnixProcessParameters() y childProcessModifier().
[override virtual] bool QProcess::waitForBytesWritten(int msecs = 30000)
Reimplementa: QIODevice::waitForBytesWritten(int msecs).
bool QProcess::waitForFinished(int msecs = 30000)
Queda bloqueada hasta que el proceso haya finalizado y se haya emitido la señal ` finished()`, o hasta que hayan transcurrido ` msecs ` milisegundos.
Devuelve true si el proceso ha finalizado; en caso contrario, devuelve false (si se ha agotado el tiempo de espera de la operación, si se ha producido un error o si este QProcess ya ha finalizado).
Esta función puede funcionar sin un bucle de eventos. Resulta útil al escribir aplicaciones sin interfaz gráfica de usuario y al realizar operaciones de E/S en un hilo que no sea de la interfaz gráfica de usuario.
Advertencia: Llamar a esta función desde el hilo principal (GUI) podría provocar que la interfaz de usuario se bloquee.
Si msecs es -1, esta función no tendrá límite de tiempo.
Véanse también finished(), waitForStarted(), waitForReadyRead() y waitForBytesWritten().
[override virtual] bool QProcess::waitForReadyRead(int msecs = 30000)
Reimplementa: QIODevice::waitForReadyRead(int msecs).
bool QProcess::waitForStarted(int msecs = 30000)
Queda bloqueada hasta que el proceso se haya iniciado y se haya emitido la señal ` started()`, o hasta que hayan transcurrido ` msecs ` milisegundos.
Devuelve true si el proceso se ha iniciado correctamente; en caso contrario, devuelve false (si se ha agotado el tiempo de espera de la operación o si se ha producido un error). Si el proceso ya se había iniciado correctamente antes de llamar a esta función, esta devuelve el resultado de forma inmediata.
Esta función puede funcionar sin un bucle de eventos. Resulta útil al escribir aplicaciones sin interfaz gráfica de usuario y al realizar operaciones de E/S en un hilo que no sea de la interfaz gráfica de usuario.
Advertencia: Llamar a esta función desde el hilo principal (de la interfaz gráfica de usuario) podría provocar que la interfaz de usuario se cuelgue.
Si msecs es -1, esta función no tendrá límite de tiempo.
Véase también started(), waitForReadyRead(), waitForBytesWritten() y waitForFinished().
QString QProcess::workingDirectory() const
Si se ha asignado un directorio de trabajo a ` QProcess `, esta función devuelve el directorio de trabajo al que accederá ` QProcess ` antes de que se inicie el programa. En caso contrario (es decir, si no se ha asignado ningún directorio), se devuelve una cadena vacía y ` QProcess ` utilizará, en su lugar, el directorio de trabajo actual de la aplicación.
Véase también setWorkingDirectory().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.