128 lines
5.0 KiB
Plaintext
128 lines
5.0 KiB
Plaintext
|
[section:launchers Launcher]
|
||
|
|
|
||
|
|
The process creation is done by a process_launcher.
|
||
|
|
The constructor of `process` will use the default_launcher, which varies by system.
|
||
|
|
There are additional launcher available on most systems.
|
||
|
|
|
||
|
|
[table:launchers Launcher overview
|
||
|
|
[[Name] [Summary] [Default on] [Available on]]
|
||
|
|
[[`windows::default_launcher`] [Launcher using `CreateProcessW`] [windows] [windows]]
|
||
|
|
[[`windows::as_user_launcher`] [Launcher using `CreateProcessAsUserW`] [] [windows]]
|
||
|
|
[[`windows::with_logon_launcher`] [Launcher using `CreateProcessWithLogonW`] [] [windows]]
|
||
|
|
[[`windows::with_token_launcher`] [Launcher using `CreateProcessWithTokenW`] [] [windows]]
|
||
|
|
[[`posix::default_launcher`] [Launcher using fork & an error pipe] [most of posix] [posix]]
|
||
|
|
[[`posix::fork_and_forget`] [Launcher using fork without error pipe] [] [posix]]
|
||
|
|
[[`posix::pdfork_launcher`] [Launcher using pdfork with an error pipe] [FreeBSD] [FreeBSD]]
|
||
|
|
[[`posix::vfork_launcher`] [Launcher using vfork] [] [posix]]
|
||
|
|
]
|
||
|
|
|
||
|
|
A launcher is invoked through the call operator.
|
||
|
|
|
||
|
|
```
|
||
|
|
auto l = windows::as_user_launcher((HANDLE)0xDEADBEEF);
|
||
|
|
asio::io_context ctx;
|
||
|
|
boost::system::error_code ec;
|
||
|
|
auto proc = l(ctx, ec, "C:\\User\\boost\\Downloads\\totally_not_a_virus.exe", {});
|
||
|
|
```
|
||
|
|
|
||
|
|
The launcher will call certain functions on the initializer if they're present, as documented below.
|
||
|
|
The initializer are used to modify the process behaviour.
|
||
|
|
|
||
|
|
[section:linux Linux Launchers]
|
||
|
|
|
||
|
|
The default and pdfork launchers on linux open an internal pipe to communicate errors that occur after forking back to the parent process.
|
||
|
|
|
||
|
|
This can be prevented by using the `fork_and_forget_launcher`.
|
||
|
|
Alternatively, the `vfork_launcher` can report errors directly back to the parent process.
|
||
|
|
|
||
|
|
Thus some calls to the initializers occur after forking from the child process.
|
||
|
|
|
||
|
|
```
|
||
|
|
struct custom_initializer
|
||
|
|
{
|
||
|
|
// functions called from the parent process:
|
||
|
|
|
||
|
|
|
||
|
|
// called before a call to fork. A returned error will cancel the launch.
|
||
|
|
template<typename Launcher>
|
||
|
|
error_code on_setup(Launcher & launcher, const filesystem::path &executable, const char * const * (&cmd_line));
|
||
|
|
|
||
|
|
// called for every initializer if an error occurred during setup or process creation
|
||
|
|
template<typename Launcher>
|
||
|
|
void on_error(Launcher & launcher, const filesystem::path &executable, const char * const * (&cmd_line),
|
||
|
|
const error_code & ec);
|
||
|
|
|
||
|
|
// called after successful process creation
|
||
|
|
template<typename Launcher>
|
||
|
|
void on_success(Launcher & launcher, const filesystem::path &executable, const char * const * (&cmd_line));
|
||
|
|
|
||
|
|
// called for every initializer if an error occurred when forking, in addition to on_error.
|
||
|
|
template<typename Launcher>
|
||
|
|
void on_fork_error(Launcher & launcher, const filesystem::path &executable, const char * const * (&cmd_line),
|
||
|
|
const error_code & ec);
|
||
|
|
|
||
|
|
|
||
|
|
// called before a call to execve. A returned error will cancel the launch. Called from the child process.
|
||
|
|
template<typename Launcher>
|
||
|
|
error_code on_exec_setup(Launcher & launcher, const filesystem::path &executable, const char * const * (&cmd_line));
|
||
|
|
|
||
|
|
|
||
|
|
// called after a failed call to execve from the child process.
|
||
|
|
template<typename Launcher>
|
||
|
|
void on_exec_error(Launcher & launcher, const filesystem::path &executable, const char * const * (&cmd_line));
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
The call sequence on success:
|
||
|
|
'''
|
||
|
|
<imagedata fileref="boost_process/posix_success.svg"/>
|
||
|
|
'''
|
||
|
|
|
||
|
|
The call sequence when fork fails:
|
||
|
|
'''
|
||
|
|
<imagedata fileref="boost_process/posix_fork_err.svg"/>
|
||
|
|
'''
|
||
|
|
|
||
|
|
The call sequence when exec fails:
|
||
|
|
'''
|
||
|
|
<imagedata fileref="boost_process/posix_exec_err.svg"/>
|
||
|
|
'''
|
||
|
|
|
||
|
|
The launcher will close all non-whitelisted file descriptors after `on_exec_setup`.
|
||
|
|
|
||
|
|
[endsect]
|
||
|
|
|
||
|
|
[section:windows Windows Launchers]
|
||
|
|
|
||
|
|
Windows launchers are pretty straight forward, they will call the following functions on the initializer if present.
|
||
|
|
|
||
|
|
```
|
||
|
|
struct custom_initializer
|
||
|
|
{
|
||
|
|
// called before a call to CreateProcess. A returned error will cancel the launch.
|
||
|
|
template<typename Launcher>
|
||
|
|
error_code on_setup(Launcher & launcher, const filesystem::path &executable, std::wstring &cmd_line);
|
||
|
|
|
||
|
|
// called for every initializer if an error occurred during setup or process creation
|
||
|
|
template<typename Launcher>
|
||
|
|
void on_error(Launcher & launcher, const filesystem::path &executable, std::wstring &cmd_line,
|
||
|
|
const error_code & ec);
|
||
|
|
|
||
|
|
// called after successful process creation
|
||
|
|
template<typename Launcher>
|
||
|
|
void on_success(Launcher & launcher, const filesystem::path &executable, std::wstring &cmd_line);
|
||
|
|
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
[note All the additional launchers for windows inherit `default_launcher`]
|
||
|
|
|
||
|
|
The call sequence is as follows:
|
||
|
|
'''
|
||
|
|
<imagedata fileref="boost_process/windows_exec.svg"/>
|
||
|
|
'''
|
||
|
|
|
||
|
|
[endsect]
|
||
|
|
|
||
|
|
|
||
|
|
[endsect]
|