[section Tutorial]

[section Header files]

Boost.Process is a header-only library. It comes with a convenience header file which is the only one you need to include to make use of all library features:

    #include <boost/process.hpp>


[note The header files [headerref boost/process/posix.hpp] and [headerref boost/process/windows.hpp] are not included by [headerref boost/process.hpp]. They provide platform-specific extensions. ]

[endsect]

[section Starting a program]

    #include <boost/process/child.hpp>

To start a process in the regular way, the construction of a [classref boost::process::child], which will automatically launch a child process.

[import ../example/execute.cpp]
[execute]

There are three possibilities to launch a process in boost.process.

[section Child]

The standard version is to create a child, which will spawn the process.

    child c("ls");

This will create an attached child process.

[endsect]

[section System]

As a convenience, the [funcref boost::process::system] function is provided. It works as std::system, though it allows
all the properties boost.process provides. It will execute the process and wait for it's exit; then return the exit_code.

   int ret = system("ls");
   
[caution When used with Pipes it will almost always result in a dead-lock.]

[endsect]

[section Spawn]

Another function which is more then convenience is the  [funcref boost::process::spawn] function. 
This function starts a process and immediately detaches it. It also prevents the system from creating a zombie process.

   spawn("ls");
   
[caution There is no guarantee that the child process will survive the father process terminating. This is dependant on the Operating System.]   

[endsect]
[endsect]

[section Arguments/Command Style]

When passing arguments to the process, two styles are provided, the cmd-style and the exe-/args-style. 

The cmd style will interpret the string as a sequence of the exe and arguments and parse them as such, while the exe-/args-style will
interpret each string as an argument.

[table:id Cmd vs Exe/Args
    [[String]              [Cmd]       [Exe/Args]]
    [["gcc --version"]     [{"gcc", "--version"}]     [{"\\"gcc --version\\""}]]
] 

When using the overloading variant, a single string will result in a cmd interpretation, several strings will yield a exe-args interpretation. Both version can be set explicitly:

```
system("grep -c false /etc/passwd"); //cmd style
system("grep", "-c", "false", "/etc/passwd"); //exe-/args-

system(cmd="grep -c false /etc/passwd"); //cmd style
system(exe="grep", args={"-c", "false", "/etc/passwd"}); //exe-/args-
```

[endsect]

[section Synchronous I/O]

The simplest way to communicate with a child-process is via pipes.

```
opstream in;
ipstream out;

child c("c++filt", std_out > out, std_in < in);

in << "_ZN5boost7process8tutorialE" << endl;
std::string value;
out >> value;

c.terminate();
```

[caution This comes with the danger of dead-locks, so it should be used with care.]

[endsect]


[section Asynchronous I/O]

Boost.Process provides capacities to communicate in an asynchronous way using Boost.Asio.
To do that, the [classref boost::process::async_pipe async_pipe] class is provided, which can be used
as an I/O object directly:

```
asio::io_service ios;
async_pipe pipe;
spawn("ls", std_out > pipe, ios);

std::string buf;

boost::asio::async_read(p, buffer(buf), 
            [](const boost::system::error_code &ec, std::size_t size){});

ios.run();
```

The library also provides a shortcut for this:

```
asio::io_service ios;

std::string buf;

spawn("ls", std_out > buffer(buf), ios);

ios.run();
```

[endsect]

[endsect]