Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Reference

Header <boost/process.hpp>
Header <boost/process/args.hpp>
Header <boost/process/async.hpp>
Header <boost/process/async_pipe.hpp>
Header <boost/process/async_system.hpp>
Header <boost/process/child.hpp>
Header <boost/process/cmd.hpp>
Header <boost/process/env.hpp>
Header <boost/process/environment.hpp>
Header <boost/process/error.hpp>
Header <boost/process/exception.hpp>
Header <boost/process/exe.hpp>
Header <boost/process/extend.hpp>
Header <boost/process/filesystem.hpp>
Header <boost/process/group.hpp>
Header <boost/process/handles.hpp>
Header <boost/process/io.hpp>
Header <boost/process/locale.hpp>
Header <boost/process/pipe.hpp>
Header <boost/process/posix.hpp>
Header <boost/process/search_path.hpp>
Header <boost/process/shell.hpp>
Header <boost/process/spawn.hpp>
Header <boost/process/start_dir.hpp>
Header <boost/process/system.hpp>
Header <boost/process/windows.hpp>

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 is void(Exec &), where Exec is a template parameter. 
      unspecified on_error;      // This handler is invoked if an error occurred. The required signature is void(auto & exec, const std::error_code&), where Exec is a template parameter. 
      unspecified on_success;      // This handler is invoked if launching the process has succeeded. The required signature is void(auto & exec), where Exec is a template parameter. 
      unspecified on_fork_error;      // This handler is invoked if the fork failed. The required signature is void(auto & exec), where Exec is a template parameter. 
      unspecified on_exec_setup;      // This handler is invoked if the fork succeeded. The required signature is void(Exec &), where Exec is a template parameter. 
      unspecified on_exec_error;      // This handler is invoked if the exec call errored. The required signature is void(auto & exec), where Exec 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 & ec);
    bool is_stream_handle(native_handle_type);
    bool is_stream_handle(native_handle_type handle, std::error_code & ec);
  }
}

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] Note

boost/process/async.hpp must also be included for this to work.

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;
    }
  }
}

[Warning] Warning

Only available on posix. See the documentation of fork, execve and 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] Warning

Only available on windows. See the parameter documentation of ShowWindow for more details.


PrevUpHomeNext