wxWidgets: Process Control

| Version: 3.2.2

Classes | Enumerations | Functions
Process Control
Functions and Macros by Category

## Detailed Description

The functions in this section are used to launch or terminate the other processes.

## Classes
struct | wxExecuteEnv
| This structure can optionally be passed to wxExecute() to specify additional options to use for the child process. More...

## Enumerations
enum | { wxEXEC_ASYNC = 0 , wxEXEC_SYNC = 1 , wxEXEC_SHOW_CONSOLE = 2 , wxEXEC_MAKE_GROUP_LEADER = 4 , wxEXEC_NODISABLE = 8 , wxEXEC_NOEVENTS = 16 , wxEXEC_HIDE_CONSOLE = 32 , wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS }
| Bit flags that can be used with wxExecute(). More...

## Functions
void | wxExit ()
| Exits application after calling wxApp::OnExit. More...
long | wxExecute (const wxString &command, int flags=wxEXEC_ASYNC, wxProcess *callback=NULL, const wxExecuteEnv *env=NULL)
| Executes another program in Unix or Windows. More...
long | wxExecute (const char *const *argv, int flags=wxEXEC_ASYNC, wxProcess *callback=NULL, const wxExecuteEnv *env=NULL)
| This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information. More...
long | wxExecute (const wchar_t *const *argv, int flags=wxEXEC_ASYNC, wxProcess *callback=NULL, const wxExecuteEnv *env=NULL)
long | wxExecute (const wxString &command, wxArrayString &output, int flags=0, const wxExecuteEnv *env=NULL)
| This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information. More...
long | wxExecute (const wxString &command, wxArrayString &output, wxArrayString &errors, int flags=0, const wxExecuteEnv *env=NULL)
| This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information. More...
unsigned long | wxGetProcessId ()
| Returns the number uniquely identifying the current process in the system. More...
int | wxKill (long pid, wxSignal sig=wxSIGTERM, wxKillError *rc=NULL, int flags=wxKILL_NOCHILDREN)
| Equivalent to the Unix kill function: send the given signal sig to the process with PID pid. More...
bool | wxShell (const wxString &command=wxEmptyString)
| Executes a command in an interactive shell window. More...
bool | wxShutdown (int flags=wxSHUTDOWN_POWEROFF)
| This function shuts down or reboots the computer depending on the value of the flags. More...

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

Bit flags that can be used with wxExecute().

Enumerator
wxEXEC_ASYNC | Execute the process asynchronously. Notice that, due to its value, this is the default.
wxEXEC_SYNC | Execute the process synchronously.
wxEXEC_SHOW_CONSOLE | Always show the child process console under MSW. The child console is hidden by default if the child IO is redirected, this flag allows changing this and showing it nevertheless. This flag is ignored under the other platforms.
wxEXEC_MAKE_GROUP_LEADER | Make the new process a group leader. Under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill() kills all children as well as pid. Under MSW, applies only to console applications. It corresponds to the native `CREATE_NEW_PROCESS_GROUP` and, in particular, ensures that Ctrl-Break signals will be sent to all children of this process as well to the process itself. Support for this flag under MSW was added in version 2.9.4 of wxWidgets.
wxEXEC_NODISABLE | Don't disable the program UI while running the child synchronously. By default synchronous execution disables all program windows to avoid that the user interacts with the program while the child process is running, you can use this flag to prevent this from happening. This flag can only be used with wxEXEC_SYNC.
wxEXEC_NOEVENTS | Don't dispatch events while the child process is executed. By default, the event loop is run while waiting for synchronous execution to complete and this flag can be used to simply block the main process until the child process finishes This flag can only be used with wxEXEC_SYNC.
wxEXEC_HIDE_CONSOLE | Hide child process console under MSW. Under MSW, hide the console of the child process if it has one, even if its IO is not redirected. This flag is ignored under the other platforms. Since 2.9.3
wxEXEC_BLOCK | Convenient synonym for flags given system()-like behaviour.

## Function Documentation

## ◆ wxExecute() [1/5]

long wxExecute | ( | const char *const * | argv,
|  | int | flags = `wxEXEC_ASYNC`,
|  | wxProcess * | callback = `NULL`,
|  | const wxExecuteEnv * | env = `NULL`
| ) |  |

This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information.

This version takes an array of values: a command, any number of arguments, terminated by NULL.

Parameters

  argv | The command to execute should be the first element of this array, any additional ones are the command parameters and the array must be terminated with a NULL pointer.
  flags | Same as for wxExecute(const wxString&,int,wxProcess*) overload.
  callback | An optional pointer to wxProcess.
  env | An optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.

See also
  wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

    #include <wx/utils.h>

wxPerl Note: In wxPerl this function is called `Wx::ExecuteArgs`.

## ◆ wxExecute() [2/5]

long wxExecute | ( | const wchar_t *const * | argv,
|  | int | flags = `wxEXEC_ASYNC`,
|  | wxProcess * | callback = `NULL`,
|  | const wxExecuteEnv * | env = `NULL`
| ) |  |

## ◆ wxExecute() [3/5]

long wxExecute | ( | const wxString & | command,
|  | int | flags = `wxEXEC_ASYNC`,
|  | wxProcess * | callback = `NULL`,
|  | const wxExecuteEnv * | env = `NULL`
| ) |  |

Executes another program in Unix or Windows.

In the overloaded versions of this function, if flags parameter contains `wxEXEC_ASYNC` flag (the default), flow of control immediately returns. If it contains `wxEXEC_SYNC`, the current application waits until the other program has terminated.

In the case of synchronous execution, the return value is the exit code of the process (which terminates by the moment the function returns) and will be -1 if the process couldn't be started and typically 0 if the process terminated successfully. Also, while waiting for the process to terminate, wxExecute() will call wxYield(). Because of this, by default this function disables all application windows to avoid unexpected reentrancies which could result from the users interaction with the program while the child process is running. If you are sure that it is safe to not disable the program windows, you may pass `wxEXEC_NODISABLE` flag to prevent this automatic disabling from happening.

For asynchronous execution, however, the return value is the process id and zero value indicates that the command could not be executed. As an added complication, the return value of -1 in this case indicates that we didn't launch a new process, but connected to the running one (this can only happen when using DDE under Windows for command execution). In particular, in this case only, the calling code will not get the notification about process termination.

If callback isn't NULL and if execution is asynchronous, wxProcess::OnTerminate() will be called when the process finishes. Specifying this parameter also allows you to redirect the standard input and/or output of the process being launched by calling wxProcess::Redirect().

Under Windows, when launching a console process its console is shown by default but hidden if its IO is redirected. Both of these default behaviours may be overridden: if wxEXEC_HIDE_CONSOLE is specified, the console will never be shown. If wxEXEC_SHOW_CONSOLE is used, the console will be shown even if the child process IO is redirected. Neither of these flags affect non-console Windows applications or does anything under the other systems.

Under Unix the flag `wxEXEC_MAKE_GROUP_LEADER` may be used to ensure that the new process is a group leader (this will create a new session if needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as well as all of its children (except those which have started their own session). Under MSW, this flag can be used with console processes only and corresponds to the native `CREATE_NEW_PROCESS_GROUP` flag.

The `wxEXEC_NOEVENTS` flag prevents processing of any events from taking place while the child process is running. It should be only used for very short-lived processes as otherwise the application windows risk becoming unresponsive from the users point of view. As this flag only makes sense with `wxEXEC_SYNC`, `wxEXEC_BLOCK` equal to the sum of both of these flags is provided as a convenience.

Note
  Currently wxExecute() can only be used from the main thread, calling this function from another thread will result in an assert failure in debug build and won't work.

Parameters

  command | The command to execute and any parameters to pass to it as a single string, i.e. "emacs file.txt".
  flags | Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include wxEXEC_SHOW_CONSOLE, wxEXEC_HIDE_CONSOLE, wxEXEC_MAKE_GROUP_LEADER (in either case) or wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to their combination, in wxEXEC_SYNC case.
  callback | An optional pointer to wxProcess.
  env | An optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.

See also
  wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

    #include <wx/utils.h>

wxPerl Note: In wxPerl this function is called `Wx::ExecuteCommand`.

## ◆ wxExecute() [4/5]

long wxExecute | ( | const wxString & | command,
|  | wxArrayString & | output,
|  | int | flags = `0`,
|  | const wxExecuteEnv * | env = `NULL`
| ) |  |

This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information.

This version can be used to execute a process (always synchronously, the contents of flags is or'd with `wxEXEC_SYNC`) and capture its output in the array output.

Parameters

  command | The command to execute and any parameters to pass to it as a single string.
  output | The string array where the stdout of the executed process is saved.
  flags | Combination of flags to which wxEXEC_SYNC is always implicitly added.
  env | An optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.

See also
  wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

    #include <wx/utils.h>

wxPerl Note: This function is called `Wx::ExecuteStdout:` it only takes the command argument, and returns a 2-element list (`status`, `output`), where `output` in an array reference.

## ◆ wxExecute() [5/5]

long wxExecute | ( | const wxString & | command,
|  | wxArrayString & | output,
|  | wxArrayString & | errors,
|  | int | flags = `0`,
|  | const wxExecuteEnv * | env = `NULL`
| ) |  |

This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information.

This version adds the possibility to additionally capture the messages from standard error output in the errors array. As with the above overload capturing standard output only, execution is always synchronous.

Parameters

  command | The command to execute and any parameters to pass to it as a single string.
  output | The string array where the stdout of the executed process is saved.
  errors | The string array where the stderr of the executed process is saved.
  flags | Combination of flags to which wxEXEC_SYNC is always implicitly added.
  env | An optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.

See also
  wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

    #include <wx/utils.h>

wxPerl Note: This function is called `Wx::ExecuteStdoutStderr:` it only takes the command argument, and returns a 3-element list (`status`, `output`, `errors`), where `output` and `errors` are array references.

## ◆ wxExit()

void wxExit | ( |  | ) |

Exits application after calling wxApp::OnExit.

Should only be used in an emergency: normally the top-level frame should be deleted (after deleting all other frames) to terminate the application. See wxCloseEvent and wxApp.

Include file:

    #include <wx/app.h>

## ◆ wxGetProcessId()

unsigned long wxGetProcessId | ( |  | ) |

Returns the number uniquely identifying the current process in the system.

If an error occurs, 0 is returned.

Include file:

    #include <wx/utils.h>

## ◆ wxKill()

int wxKill | ( | long | pid,
|  | wxSignal | sig = `wxSIGTERM`,
|  | wxKillError * | rc = `NULL`,
|  | int | flags = `wxKILL_NOCHILDREN`
| ) |  |

Equivalent to the Unix kill function: send the given signal sig to the process with PID pid.

The valid signal values are:

enum wxSignal
{
wxSIGNONE = 0, // verify if the process exists under Unix
wxSIGHUP,
wxSIGINT,
wxSIGQUIT,
wxSIGILL,
wxSIGTRAP,
wxSIGABRT,
wxSIGEMT,
wxSIGFPE,
wxSIGKILL, // forcefully kill, dangerous!
wxSIGBUS,
wxSIGSEGV,
wxSIGSYS,
wxSIGPIPE,
wxSIGALRM,
wxSIGTERM // terminate the process gently
};
wxSignal
wxSignal
Signal constants used by wxProcess.
Definition: utils.h:12
wxSIGILL
@ wxSIGILL
Definition: utils.h:17
wxSIGPIPE
@ wxSIGPIPE
Definition: utils.h:26
wxSIGFPE
@ wxSIGFPE
Definition: utils.h:21
wxSIGTRAP
@ wxSIGTRAP
Definition: utils.h:18
wxSIGQUIT
@ wxSIGQUIT
Definition: utils.h:16
wxSIGBUS
@ wxSIGBUS
Definition: utils.h:23
wxSIGABRT
@ wxSIGABRT
Definition: utils.h:19
wxSIGSEGV
@ wxSIGSEGV
Definition: utils.h:24
wxSIGEMT
@ wxSIGEMT
Definition: utils.h:20
wxSIGSYS
@ wxSIGSYS
Definition: utils.h:25
wxSIGALRM
@ wxSIGALRM
Definition: utils.h:27
wxSIGTERM
@ wxSIGTERM
terminate the process gently
Definition: utils.h:28
wxSIGNONE
@ wxSIGNONE
verify if the process exists under Unix
Definition: utils.h:13
wxSIGINT
@ wxSIGINT
Definition: utils.h:15
wxSIGKILL
@ wxSIGKILL
forcefully kill, dangerous!
Definition: utils.h:22
wxSIGHUP
@ wxSIGHUP
Definition: utils.h:14

`wxSIGNONE`, `wxSIGKILL` and `wxSIGTERM` have the same meaning under both Unix and Windows but all the other signals are equivalent to `wxSIGTERM` under Windows. Moreover, under Windows, `wxSIGTERM` is implemented by posting a message to the application window, so it only works if the application does have windows. If it doesn't, as is notably always the case for the console applications, you need to use `wxSIGKILL` to actually kill the process. Of course, this doesn't allow the process to shut down gracefully and so should be avoided if possible.

Returns 0 on success, -1 on failure. If the rc parameter is not NULL, it will be filled with a value from the `wxKillError` enum:

enum wxKillError
{
wxKILL_OK, // no error
wxKILL_BAD_SIGNAL, // no such signal
wxKILL_ACCESS_DENIED, // permission denied
wxKILL_NO_PROCESS, // no such process
wxKILL_ERROR // another, unspecified error
};
wxKillError
wxKillError
Return values for wxProcess::Kill.
Definition: utils.h:35
wxKILL_BAD_SIGNAL
@ wxKILL_BAD_SIGNAL
no such signal
Definition: utils.h:37
wxKILL_ERROR
@ wxKILL_ERROR
another, unspecified error
Definition: utils.h:40
wxKILL_NO_PROCESS
@ wxKILL_NO_PROCESS
no such process
Definition: utils.h:39
wxKILL_OK
@ wxKILL_OK
no error
Definition: utils.h:36
wxKILL_ACCESS_DENIED
@ wxKILL_ACCESS_DENIED
permission denied
Definition: utils.h:38

The flags parameter can be wxKILL_NOCHILDREN (the default), or wxKILL_CHILDREN, in which case the child processes of this process will be killed too. Note that under Unix, for wxKILL_CHILDREN to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER to wxExecute().

See also
  wxProcess::Kill(), wxProcess::Exists(), External Program Execution Sample

Include file:

    #include <wx/utils.h>

## ◆ wxShell()

bool wxShell | ( | const wxString & | command = `wxEmptyString` | ) |

Executes a command in an interactive shell window.

If no command is specified, then just the shell is spawned.

See also
  wxExecute(), External Program Execution Sample

Include file:

    #include <wx/utils.h>

## ◆ wxShutdown()

bool wxShutdown | ( | int | flags = `wxSHUTDOWN_POWEROFF` | ) |

This function shuts down or reboots the computer depending on the value of the flags.

Note
  Note that performing the shutdown requires the corresponding access rights (superuser under Unix, SE_SHUTDOWN privilege under Windows) and that this function is only implemented under Unix and MSW.

Parameters

  flags | One of `wxSHUTDOWN_POWEROFF`, `wxSHUTDOWN_REBOOT` or `wxSHUTDOWN_LOGOFF` (currently implemented only for MSW) possibly combined with `wxSHUTDOWN_FORCE` which forces shutdown under MSW by forcefully terminating all the applications. As doing this can result in a data loss, this flag shouldn't be used unless really necessary.

Returns
  true on success, false if an error occurred.

Include file:

    #include <wx/utils.h>