# Poco

# class Process

Library: Foundation
Package: Processes
Header: Poco/Process.h

## Description

This class provides methods for working with processes.

## Inheritance

Direct Base Classes: ProcessImpl

All Base Classes: ProcessImpl

## Member Summary

Member Functions: id, isRunning, kill, launch, requestTermination, times, timesMicroseconds, tryWait, wait

Inherited Functions: escapeArg, idImpl, isRunningImpl, killImpl, launchImpl, mustEscapeArg, requestTerminationImpl, terminationEventName, timesImpl, timesMicrosecondsImpl

## Types Aliases

### Args

using Args = ArgsImpl;

### Env

using Env = EnvImpl;

### PID

using PID = PIDImpl;

## Member Functions

### id

static PID id();

Returns the process ID of the current process.

### isRunning

static bool isRunning(
const ProcessHandle & handle
);

check if the process specified by handle is running or not

This is preferable on Windows where process IDs may be reused.

### isRunning

static bool isRunning(
PID pid
);

Check if the process specified by given pid is running or not.

### kill

static void kill(
ProcessHandle & handle
);

Kills the process specified by handle.

This is preferable on Windows where process IDs may be reused.

### kill

static void kill(
PID pid
);

Kills the process with the given pid.

### launch

static ProcessHandle launch(
const std::string & command,
const Args & args,
int options = 0
);

Creates a new process for the given command and returns a ProcessHandle of the new process. The given arguments are passed to the command on the command line.

### launch

static ProcessHandle launch(
const std::string & command,
const Args & args,
const std::string & initialDirectory,
int options = 0
);

Creates a new process for the given command and returns a ProcessHandle of the new process. The given arguments are passed to the command on the command line. The process starts executing in the specified initial directory.

### launch

static ProcessHandle launch(
const std::string & command,
const Args & args,
Pipe * inPipe,
Pipe * outPipe,
Pipe * errPipe,
int options = 0
);

Creates a new process for the given command and returns a ProcessHandle of the new process. The given arguments are passed to the command on the command line.

If inPipe, outPipe or errPipe is non-null, the corresponding standard input, standard output or standard error stream of the launched process is redirected to the Pipe. PipeInputStream or PipeOutputStream can be used to send receive data from, or send data to the process.

Note: the same Pipe can be used for both outPipe and errPipe.

After a Pipe has been passed as inPipe, only write operations are valid. After a Pipe has been passed as outPipe or errPipe, only read operations are valid.

It is forbidden to pass the same pipe as inPipe and outPipe or errPipe.

Usage example:

    Pipe outPipe;
    Process::Args args;
    ProcessHandle ph(launch("/bin/ps", args, 0, &outPipe, 0));
    PipeInputStream istr(outPipe);
    ... // read output of ps from istr
    int rc = ph.wait();

### launch

static ProcessHandle launch(
const std::string & command,
const Args & args,
const std::string & initialDirectory,
Pipe * inPipe,
Pipe * outPipe,
Pipe * errPipe,
int options = 0
);

Creates a new process for the given command and returns a ProcessHandle of the new process. The given arguments are passed to the command on the command line. The process starts executing in the specified initial directory.

If inPipe, outPipe or errPipe is non-null, the corresponding standard input, standard output or standard error stream of the launched process is redirected to the Pipe. PipeInputStream or PipeOutputStream can be used to send receive data from, or send data to the process.

Note: the same Pipe can be used for both outPipe and errPipe.

After a Pipe has been passed as inPipe, only write operations are valid. After a Pipe has been passed as outPipe or errPipe, only read operations are valid.

It is forbidden to pass the same pipe as inPipe and outPipe or errPipe.

Usage example:

    Pipe outPipe;
    Process::Args args;
    ProcessHandle ph(launch("/bin/ps", args, 0, &outPipe, 0));
    PipeInputStream istr(outPipe);
    ... // read output of ps from istr
    int rc = ph.wait();

### launch

static ProcessHandle launch(
const std::string & command,
const Args & args,
Pipe * inPipe,
Pipe * outPipe,
Pipe * errPipe,
const Env & env,
int options = 0
);

Creates a new process for the given command and returns a ProcessHandle of the new process. The given arguments are passed to the command on the command line.

If inPipe, outPipe or errPipe is non-null, the corresponding standard input, standard output or standard error stream of the launched process is redirected to the Pipe.

The launched process is given the specified environment variables.

### launch

static ProcessHandle launch(
const std::string & command,
const Args & args,
const std::string & initialDirectory,
Pipe * inPipe,
Pipe * outPipe,
Pipe * errPipe,
const Env & env,
int options = 0
);

Creates a new process for the given command and returns a ProcessHandle of the new process. The given arguments are passed to the command on the command line. The process starts executing in the specified initial directory. If inPipe, outPipe or errPipe is non-null, the corresponding standard input, standard output or standard error stream of the launched process is redirected to the Pipe. The launched process is given the specified environment variables.

### requestTermination

static void requestTermination(
PID pid
);

Requests termination of the process with the give PID.

On Unix platforms, this will send a SIGINT to the process and thus work with arbitrary processes.

On other platforms, a global event flag will be set. Setting the flag will cause Util::ServerApplication::waitForTerminationRequest() to return. Therefore this will only work with applications based on Util::ServerApplication.

### times

static void times(
long & userTime,
long & kernelTime
);

Returns the number of seconds spent by the current process in user and kernel mode.

### timesMicroseconds

static void timesMicroseconds(
Poco::Int64 & userTime,
Poco::Int64 & kernelTime
);

Returns the number of microseconds spent by the current process in user and kernel mode.

### tryWait

static int tryWait(
const ProcessHandle & handle
);

Checks that process is finished and returns the exit code of the process. If the process is still running, returns -1.

### wait

static int wait(
const ProcessHandle & handle
);

Waits for the process specified by handle to terminate and returns the exit code of the process.