# class KProcess

###

Module | kdecore
Namespace |
Class | KProcess
Inherits | QProcess

\class KProcess kprocess.h <KProcess>

Child process invocation, monitoring and control.

This class extends QProcess by some useful functionality, overrides some defaults with saner values and wraps parts of the API into a more accessible one. This is the preferred way of spawning child processes in KDE; don't use QProcess directly.

Author Oswald Buddenhagen <ossi@kde.org>

### enums

- OutputChannelMode { SeparateChannels, MergedChannels, ForwardedChannels, OnlyStdoutChannel, OnlyStderrChannel }

enum details

### methods

- KProcess (parent)

  returns ctor
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  parent | QObject | 0

  Constructor

- KProcess (d, parent)

  returns ctor
  Not implemented

  Argument | Type | Default
  --- | --- | ---
  d | KProcessPrivate |
  parent | QObject |

  Internal

- KProcess (a0)

  returns ctor
  before KDE 4.1.0 only

  Argument | Type | Default
  --- | --- | ---
  a0 | QObject | 0

- clearEnvironment ( )

  returns Nothing

  Empties the process' environment.

  Note that LD_LIBRARY_PATH/DYLD_LIBRARY_PATH is automatically added on *NIX.

  This function must be called before starting the process.

- clearProgram ( )

  returns Nothing

  Clear the program and command line argument list.

- execute (msecs)

  returns int

  Argument | Type | Default
  --- | --- | ---
  msecs | int | -1

  Start the process, wait for it to finish, and return the exit code.

  This method is roughly equivalent to the sequence: `start(); waitForFinished(msecs); return exitCode();`

  Unlike the other execute() variants this method is not static, so the process can be parametrized properly and talked to.

  msecs - time to wait for process to exit before killing it Returns -2 if the process could not be started, -1 if it crashed, otherwise its exit code

- execute (exe, args, msecs)

  returns int
  static

  Argument | Type | Default
  --- | --- | ---
  exe | QString |
  args | QStringList | QStringList()
  msecs | int | -1

  exe - the program to execute

  args - the command line arguments for the program, one per list element

  msecs - time to wait for process to exit before killing it Returns -2 if the process could not be started, -1 if it crashed, otherwise its exit code

- execute (argv, msecs)

  returns int
  static

  Argument | Type | Default
  --- | --- | ---
  argv | QStringList |
  msecs | int | -1

  argv - the program to execute and the command line arguments for the program, one per list element

  msecs - time to wait for process to exit before killing it Returns -2 if the process could not be started, -1 if it crashed, otherwise its exit code

- operator << (arg)

  returns KProcess

  Argument | Type | Default
  --- | --- | ---
  arg | QString |

  Append an element to the command line argument list for this process.

  If no executable is set yet, it will be set instead.

  For example, doing an "ls -l /usr/local/bin" can be achieved by:

      KProcess p;
      p << "ls" << "-l" << "/usr/local/bin";
      ...

  This function must be called before starting the process, obviously.

  arg - the argument to add Returns a reference to this KProcess

- operator << (args)

  returns KProcess

  Argument | Type | Default
  --- | --- | ---
  args | QStringList |

  args - the arguments to add Returns a reference to this KProcess

- outputChannelMode ( )

  returns KProcess.OutputChannelMode

  Query how the output channels of the child process are handled.

  Returns the output channel handling mode

- pid ( )

  returns int

  Obtain the process' ID as known to the system.

  Unlike with QProcess.pid(), this is a real PID also on Windows.

  This function can be called only while the process is running. It cannot be applied to detached processes.

  Returns the process ID

- program ( )

  returns QStringList

  Obtain the currently set program and arguments.

  Returns a list, the first element being the program, the remaining ones being command line arguments to the program.

- setEnv (name, value, overwrite)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  value | QString |
  overwrite | bool | 1

  Adds the variable name to the process' environment.

  This function must be called before starting the process.

  name - the name of the environment variable

  value - the new value for the environment variable

  overwrite - if false and the environment variable is already set, the old value will be preserved

- setNextOpenMode (mode)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  mode | QIODevice.OpenMode |

  Set the QIODevice open mode the process will be opened in.

  This function must be called before starting the process, obviously.

  mode - the open mode. Note that this mode is automatically "reduced" according to the channel modes and redirections. The default is QIODevice.ReadWrite.

- setOutputChannelMode (mode)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  mode | KProcess.OutputChannelMode |

  Set how to handle the output channels of the child process.

  The default is ForwardedChannels, which is unlike in QProcess. Do not request more than you actually handle, as this output is simply lost otherwise.

  This function must be called before starting the process.

  mode - the output channel handling mode

- setProgram (exe, args)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  exe | QString |
  args | QStringList | QStringList()

  Set the program and the command line arguments.

  This function must be called before starting the process, obviously.

  exe - the program to execute

  args - the command line arguments for the program, one per list element

- setProgram (argv)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  argv | QStringList |

  argv - the program to execute and the command line arguments for the program, one per list element

- setShellCommand (cmd)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  cmd | QString |

  Set a command to execute through a shell (a POSIX sh on *NIX and cmd.exe on Windows).

  Using this for anything but user-supplied commands is usually a bad idea, as the command's syntax depends on the platform. Redirections including pipes, etc. are better handled by the respective functions provided by QProcess.

  This function must be called before starting the process, obviously.

  cmd - the command to execute through a shell. The caller must make sure that all filenames etc. are properly quoted when passed as argument. Failure to do so often results in serious security holes. See KShell.quoteArg().

- start ( )

  returns Nothing

  Start the process.

  See also QProcess.start(const QString &, const QStringList &, OpenMode)

- startDetached ( )

  returns int

  Start the process and detach from it. See QProcess.startDetached() for details.

  Unlike the other startDetached() variants this method is not static, so the process can be parametrized properly. Currently, only the setProgram()/setShellCommand() and setWorkingDirectory() parametrizations are supported.

  The KProcess object may be re-used immediately after calling this function.

  Returns the PID of the started process or 0 on error

- startDetached (exe, args)

  returns int
  static

  Argument | Type | Default
  --- | --- | ---
  exe | QString |
  args | QStringList | QStringList()

  exe - the program to start

  args - the command line arguments for the program, one per list element Returns the PID of the started process or 0 on error

- startDetached (argv)

  returns int
  static

  Argument | Type | Default
  --- | --- | ---
  argv | QStringList |

  argv - the program to start and the command line arguments for the program, one per list element Returns the PID of the started process or 0 on error

- unsetEnv (name)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  name | QString |

  Removes the variable name from the process' environment.

  This function must be called before starting the process.

  name - the name of the environment variable

### enums - detail

- OutputChannelMode { SeparateChannels, MergedChannels, ForwardedChannels, OnlyStdoutChannel, OnlyStderrChannel }

  Modes in which the output channels can be opened.

  | SeparateChannels | - QProcess::SeparateChannels | - |
  | MergedChannels | - QProcess::MergedChannels | - |
  | ForwardedChannels | - QProcess::ForwardedChannels | - |
  | OnlyStdoutChannel | - | - |
  | OnlyStderrChannel | - | - |