| Home | Libraries | People | FAQ | More

## Global std_out

boost::process::std_out

## Synopsis

    // In header: <boost/process/io.hpp>

    unspecified std_out;

## Description

This property allows to set the output stream for the child process.

| Note
The Semantic is the same as for std_err `std_err` and `std_out` can be combined into one stream, with the `operator &`, i.e. `std_out & std_err`.

## Details

### File Input

The file I/O simple redirects the stream to a file, for which the possible types are

- `boost::filesystem::path`

- `std::basic_string<char_type>`

- `const char_type*`

- `FILE*`

with `char_type` being either `char` or `wchar_t`.

FILE* is explicitly added, so the process can easily redirect the output stream of the child to another output stream of the process. That is:

    system("ls", std_out < stdin);

| Warning
If the launching and the child process use the input, this leads to undefined behaviour.

A syntax like `system("ls", std_out > std::cerr)` is not possible, due to the C++ implementation not providing access to the handle.

The valid expressions for this property are

    std_out < file;
    std_out = file;

### Pipe Output

As explained in the corresponding section, the boost.process library provides a async_pipe class which can be used to communicate with child processes.

| Note
Technically the async_pipe works like a synchronous pipe here, since no asio implementation is used by the library here. The asynchronous operation will then however not end if the process is finished, since the pipe remains open. You can use the async_close function with on_exit to fix that.

Valid expressions with pipes are these:

    std_out > pipe;
    std_out = pipe;

Where the valid types for `pipe` are the following:

- `basic_pipe`

- `async_pipe`

- `basic_ipstream`

- `basic_pstream`

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 Pipe Output

Asynchronous Pipe I/O classifies communication which has automatically handling of the async operations by the process library. This means, that a pipe will be constructed, the async_read/-write will be automatically started, and that the end of the child process will also close the pipe.

Valid types for pipe I/O are the following:

- `boost::asio::mutable_buffer` [10]

- `boost::asio::streambuf`

- `std::future<std::vector<char>>`

- `std::future<std::string>`

Valid expressions with pipes are these:

    std_out > buffer;
    std_out = buffer;
    std_err > buffer;
    std_err = buffer;
    (std_out & std_err) > buffer;
    (std_out & std_err) = buffer;

| Note
`boost::asio::buffer` is also available in the `boost::process` namespace.

| Warning
This feature requires `boost/process/async.hpp` to be included and a reference to `boost::asio::io_service` to be passed to the launching function.

### Close

The out stream can be closed, so it cannot be write from. This will lead to an error when attempted.

This can be achieved by the following syntax.

    std_out > close;
    std_out = close;
    std_out.close();

### Null

The output stream can be redirected to write to the null-device, which means that all output is discarded.

The syntax to achieve that has the following variants:

    std_out > null;
    std_out = null;
    std_out.null();

[10] Constructed with `boost::asio::buffer`