mirror of
https://github.com/boostorg/process.git
synced 2026-01-20 04:42:24 +00:00
101 lines
3.3 KiB
Plaintext
101 lines
3.3 KiB
Plaintext
== `stdio.hpp`
|
|
[#stdio]
|
|
|
|
The initializer for the stdio of a subprocess
|
|
The subprocess stdio initializer has three members:
|
|
|
|
- in for stdin
|
|
- out for stdout
|
|
- err for stderr
|
|
|
|
If the initializer is present all three will be set for the subprocess.
|
|
By default they will inherit the stdio handles from the parent process.
|
|
This means that this will forward stdio to the subprocess:
|
|
|
|
[source,cpp]
|
|
----
|
|
asio::io_context ctx;
|
|
v2::process proc(ctx, "/bin/bash", {}, v2::process_stdio{});
|
|
----
|
|
|
|
No constructors are provided in order to support designated initializers
|
|
in later version of C++.
|
|
|
|
[source,cpp]
|
|
----
|
|
asio::io_context ctx;
|
|
|
|
/// C++17
|
|
v2::process proc17(ctx, "/bin/bash", {}, v2::process_stdio{.err=nullptr});
|
|
/// C++11 & C++14
|
|
v2::process proc17(ctx, "/bin/bash", {}, v2::process_stdio{ {}, {}, nullptr});
|
|
----
|
|
|
|
Valid initializers for any stdio are:
|
|
|
|
- `std::nullptr_t` assigning a null-device
|
|
- `FILE*` any open file, including `stdin`, `stdout` and `stderr`
|
|
- `native_handle` any native file handle (`HANDLE` on windows) or file descriptor (`int` on posix)
|
|
- any io-object with a `.native_handle()` function that is compatible with the above. E.g. a `asio::ip::tcp::socket`, or a pipe object.
|
|
- a filesystem::path, which will open a readable or writable depending on the direction of the stream
|
|
- an `asio::basic_writeable_pipe` for stdin or `asio::basic_readable_pipe` for stderr/stdout.
|
|
|
|
When passing a `FILE*`, a `native_handle` or an io-object with a `native_handle`,
|
|
the initializer will assign the handle as is to the child process.
|
|
That is the file descriptor/handle gets cloned into the subprocess and used without modification.
|
|
|
|
When passing a filesystem::path, the initializer will attempt to open the file and then pass the handle
|
|
to the subprocess.
|
|
|
|
When passing a `readable_pipe` to stdout/stderr or a `writable_pipe` to stdin by reference,
|
|
the initializer to create the other side of the pipe (`writable_pipe` for stdout/stderr, `readable_pipe` for `stdin`),
|
|
connect the pair and pass the native_handle to the child process.
|
|
|
|
That is, these two are equivalent:
|
|
|
|
.Implicit construction of the readable pipe.
|
|
[source,cpp]
|
|
----
|
|
asio::io_context ctx;
|
|
asio::writable_pipe wp{ctx};
|
|
// create a readable pipe internally and connect it to wp
|
|
process proc{ctx, "/bin/bash", {}, process_stdio{.in=wp}};
|
|
|
|
// create it explicitly
|
|
{
|
|
// the pipe the child process reads from
|
|
asio::readable_pipe rp{ctx};
|
|
asio::connect_pipe(rp, wp);
|
|
// `rp.native_handle()` will be assigned to the child processes stdin
|
|
process proc{ctx, "/bin/bash", {}, process_stdio{.in=rp}};
|
|
rp.close(); // close it so the pipe closes when the `proc exits.
|
|
}
|
|
----
|
|
|
|
The explicit version allows you to assign the same `writable_pipe` to `stdout` and `stderr`:
|
|
|
|
[source,cpp]
|
|
----
|
|
// the pipe the parent process reads from and both
|
|
// stderr & stdout of the child process write to
|
|
asio::readable_pipe rp{ctx};
|
|
asio::writable_pipe wp{ctx};
|
|
asio::connect_pipe(rp, wp);
|
|
process proc{ctx, "/bin/bash", {}, process_stdio{.out=wp, .err=wp}};
|
|
wp.close(); // close it so the pipe closes when the `proc exits.
|
|
----
|
|
|
|
NOTE: If the child writes to a pipe, the parent reads from it et vice versa.
|
|
|
|
|
|
[source,cpp]
|
|
----
|
|
/// The initializer for the stdio of a subprocess
|
|
struct process_stdio
|
|
{
|
|
__implementation_defined__ in;
|
|
__implementation_defined__ out;
|
|
__implementation_defined__ err;
|
|
};
|
|
----
|