...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Convenience header which includes all public and platform-independent boost.process header files.
This header provides the args property. It also provides the alternative name argv .
namespace boost { namespace process { unspecified args; unspecified argv; } }
The header which provides the basic asynchronous features. It provides the on_exit property, which allows callbacks when the process exits. It also implements the necessary traits for passing an boost::asio::io_context, which is needed for asynchronous communication.
It also pulls the boost::asio::buffer into the boost::process namespace for convenience.
namespace boost { namespace process { unspecified buffer; unspecified on_exit; } }
namespace boost { namespace process { class async_pipe; } }
Defines the asynchronous version of the system function.
namespace boost { namespace process { template<typename ExitHandler, typename ... Args> unspecified async_system(boost::asio::io_context &, ExitHandler &&, Args &&...); } }
Defines a child process class.
namespace boost { namespace process { class child; typedef unspecified pid_t; // Typedef for the type of an pid_t. } }
This header provides the cmd property.
namespace boost { namespace process { unspecified cmd; } }
This header which provides the env
property. It allows the modification of the environment the child process will run in, in a functional style.
namespace boost { namespace process { unspecified env; } }
For additional information see the platform documentations:
namespace boost { namespace process { template<typename Char> class basic_environment; template<typename Char> class basic_native_environment; typedef basic_native_environment< char > native_environment; // Definition of the environment for the current process. typedef basic_native_environment< wchar_t > wnative_environment; // Definition of the environment for the current process. typedef basic_environment< char > environment; // Type definition to hold a seperate environment. typedef basic_environment< wchar_t > wenvironment; // Type definition to hold a seperate environment. } namespace this_process { // Get the process id of the current process. int get_id(); // Get the native handle of the current process. native_handle_type native_handle(); // Get the enviroment of the current process. native_environment environment(); // Get the enviroment of the current process. wnative_environment wenvironment(); // Get the path environment variable of the current process runs. std::vector< boost::process::filesystem::path > path(); } }
Header which provides the error properties. It allows to explicitly set the error handling, the properties are:
namespace boost { namespace process { unspecified ignore_error; unspecified throw_on_error; unspecified error; unspecified error_ref; unspecified error_code; } }
For error there are two aliases: error_ref and error_code
namespace boost { namespace process { struct process_error; } }
Header which provides the exe property.
namespace boost { namespace process { unspecified exe; } }
This header which provides the types and functions provided for custom extensions.
Please refer to the tutorial for more details.
namespace boost { namespace process { namespace extend { struct async_handler; struct handler; template<typename Sequence> struct posix_executor; struct require_io_context; template<typename Char, typename Sequence> struct windows_executor; unspecified on_setup; // This handler is invoked before the process in launched, to setup parameters. The required signature isvoid(Exec &)
, whereExec
is a template parameter. unspecified on_error; // This handler is invoked if an error occurred. The required signature isvoid(auto & exec, const std::error_code&)
, whereExec
is a template parameter. unspecified on_success; // This handler is invoked if launching the process has succeeded. The required signature isvoid(auto & exec)
, whereExec
is a template parameter. unspecified on_fork_error; // This handler is invoked if the fork failed. The required signature isvoid(auto & exec)
, whereExec
is a template parameter. unspecified on_exec_setup; // This handler is invoked if the fork succeeded. The required signature isvoid(Exec &)
, whereExec
is a template parameter. unspecified on_exec_error; // This handler is invoked if the exec call errored. The required signature isvoid(auto & exec)
, whereExec
is a template parameter. // Helper function to get the last error code system-independent. std::error_code get_last_error(); void throw_last_error(const std::string &); void throw_last_error(); template<typename Sequence> asio::io_context & get_io_context(const Sequence &); } } }
Defines a group process class. For additional information see the platform specific implementations:
namespace boost { namespace process { class group; } }
Defines functions to obtain handles of the current process and limit the amount for inherited ones.
namespace boost { namespace process { static unspecified limit_handles; } namespace this_process { typedef unspecified native_handle_type; std::vector< native_handle_type > get_handles(); std::vector< native_handle_type > get_handles(std::error_code &); bool is_stream_handle(native_handle_type); bool is_stream_handle(native_handle_type, std::error_code &); } }
Header which provides the io properties. It provides the following properties:
namespace boost { namespace process { unspecified close; unspecified null; unspecified std_in; unspecified std_out; unspecified std_err; } }
File I/O.
The library allows full redirection of streams to files as shown below.
boost::process::filesystem::path log = "my_log_file.txt"; boost::process::filesystem::path input = "input.txt"; boost::process::filesystem::path output = "output.txt"; system("my_prog", std_out>output, std_in<input, std_err>log);
Synchronous Pipe I/O.
Another way is to communicate through pipes.
pstream str; child c("my_prog", std_out > str); int i; str >> i;
Note that the pipe may also be used between several processes, like this:
pipe p; child c1("nm", "a.out", std_out>p); child c2("c++filt", std_in<p);
Asynchronous I/O.
Utilizing boost.asio
asynchronous I/O is provided.
boost::asio::io_context ios; std::future<std::string> output; system("ls", std_out > output, ios); auto res = fut.get();
Note | |
---|---|
|
Closing.
Stream can be closed, so nothing can be read or written.
system("foo", std_in.close());
Null.
Streams can be redirected to null, which means, that written date will be discarded and read data will only contain EOF
.
system("b2", std_out > null);
namespace boost { namespace process { typedef std::codecvt< wchar_t, char, std::mbstate_t > codecvt_type; // The internally used type for code conversion. // Internally used error cateory for code conversion. const std::error_category & codecvt_category(); // Get a reference to the currently used code converter. const codecvt_type & codecvt(); // Set the locale of the library. std::locale imbue(const std::locale & loc); } }
namespace boost { namespace process { template<typename CharT, typename Traits = std::char_traits<CharT> > class basic_ipstream; template<typename CharT, typename Traits = std::char_traits<CharT> > class basic_opstream; template<typename CharT, typename Traits = std::char_traits<CharT> > class basic_pipe; template<typename CharT, typename Traits = std::char_traits<CharT> > struct basic_pipebuf; template<typename CharT, typename Traits = std::char_traits<CharT> > class basic_pstream; typedef basic_pipe< char > pipe; typedef basic_pipe< wchar_t > wpipe; typedef basic_pipebuf< char > pipebuf; typedef basic_pipebuf< wchar_t > wpipebuf; typedef basic_ipstream< char > ipstream; typedef basic_ipstream< wchar_t > wipstream; typedef basic_opstream< char > opstream; typedef basic_opstream< wchar_t > wopstream; typedef basic_pstream< char > pstream; typedef basic_pstream< wchar_t > wpstream; } }
Header which provides the posix extensions.
namespace boost { namespace process { namespace posix { unspecified fd; unspecified sig; unspecified use_vfork; } } }
Defines a function to search for an executable in path.
namespace boost { namespace process { boost::process::filesystem::path search_path(const boost::process::filesystem::path &, const std::vector< boost::process::filesystem::path > = ::boost::this_process::path()); } }
Header which provides the shell property. This provides the property to launch a process through the system shell. It also allows the user to obtain the shell-path via shell().
namespace boost { namespace process { unspecified shell; } }
Defines the spawn function.
namespace boost { namespace process { template<typename ... Args> void spawn(Args &&...); } }
Header which provides the start_dir property, which allows to set the directory the process shall be started in.
namespace boost { namespace process { unspecified start_dir; } }
Defines a system function.
namespace boost { namespace process { template<typename ... Args> int system(Args &&...); } }
Header which provides the windows extensions.
namespace boost { namespace process { namespace windows { unspecified hide; unspecified maximized; unspecified minimized; unspecified minimized_not_active; unspecified not_active; unspecified show; unspecified show_normal; unspecified create_no_window; } } }
Warning | |
---|---|
Only available on windows. See the parameter documentation of ShowWindow for more details. |