| Home | Libraries | People | FAQ | More

## Reference

### Header <boost/process/args.hpp>

This header provides the args property. It also provides the alternative name argv .

    namespace boost {
      namespace process {
        unspecified args;
        unspecified argv;
      }
    }

### Header <boost/process/async.hpp>

The header which provides the basic asynchrounous 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;
      }
    }

### Header <boost/process/async_pipe.hpp>

    namespace boost {
      namespace process {
        class async_pipe;
      }
    }

### Header <boost/process/async_system.hpp>

Defines the asynchrounous version of the system function.

    namespace boost {
      namespace process {
        template<typename ExitHandler, typename... Args>
          unspecified async_system(boost::asio::io_context &, ExitHandler &&,
                                   Args &&...);
      }
    }

### Header <boost/process/child.hpp>

Defines a child process class.

    namespace boost {
      namespace process {
        class child;

        typedef unspecified pid_t;  // Typedef for the type of an pid_t.
      }
    }

### Header <boost/process/cmd.hpp>

This header provides the cmd property.

    namespace boost {
      namespace process {
        unspecified cmd;
      }
    }

### Header <boost/process/env.hpp>

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:

- windows

- posix

### Header <boost/process/environment.hpp>

    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 {
        typedef unspecified native_handle_type;  // Definition of the native handle type.

        // 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::filesystem::path > path();
      }
    }

### Header <boost/process/error.hpp>

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

### Header <boost/process/exception.hpp>

    namespace boost {
      namespace process {
        struct process_error;
      }
    }

### Header <boost/process/exe.hpp>

Header which provides the exe property.

    namespace boost {
      namespace process {
        unspecified exe;
      }
    }

### Header <boost/process/extend.hpp>

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 handler;
          struct require_io_context;
          struct async_handler;
          template<typename Sequence> struct posix_executor;
          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 occured. 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 &);
        }
      }
    }

### Header <boost/process/group.hpp>

Defines a group process class. For additional information see the platform specific implementations:

- windows - job object

- posix - process group

    namespace boost {
      namespace process {
        class group;
      }
    }

### Header <boost/process/io.hpp>

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::filesystem::path log    = "my_log_file.txt";
    boost::filesystem::path input  = "input.txt";
    boost::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
`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);

### Header <boost/process/locale.hpp>

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

### Header <boost/process/pipe.hpp>

    namespace boost {
      namespace process {
        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_ipstream;
        template<typename CharT, typename Traits = std::char_traits<CharT> >
          class basic_opstream;
        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 <boost/process/posix.hpp>

Header which provides the posix extensions.

    namespace boost {
      namespace process {
        namespace posix {
          unspecified fd;
          unspecified sig;
          unspecified use_vfork;
        }
      }
    }

| Warning
Only available on posix. See the documentation of fork, execve and vfork.

### Header <boost/process/search_path.hpp>

Defines a function to search for an executable in path.

    namespace boost {
      namespace process {
        boost::filesystem::path
        search_path(const boost::filesystem::path &,
                    const std::vector< boost::filesystem::path > = ::boost::this_process::path());
      }
    }

### Header <boost/process/shell.hpp>

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

### Header <boost/process/spawn.hpp>

Defines the spawn function.

    namespace boost {
      namespace process {
        template<typename... Args> void spawn(Args &&...);
      }
    }

### Header <boost/process/start_dir.hpp>

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

### Header <boost/process/system.hpp>

Defines a system function.

    namespace boost {
      namespace process {
        template<typename... Args> int system(Args &&...);
      }
    }

### Header <boost/process/windows.hpp>

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.