mirror of
https://github.com/boostorg/process.git
synced 2026-01-25 06:22:14 +00:00
140 lines
3.8 KiB
Plaintext
140 lines
3.8 KiB
Plaintext
[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-
|
|
```
|
|
|
|
[note If a '"' sign is used in the argument style, it will be passed as part of the argument.
|
|
If the same effect it wanted with the cmd syntax, it ought to be escaped, i.e. '\\\"'. ]
|
|
[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]
|