1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
5 <title>Design Rationale</title>
6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
9 <link rel="up" href="../process.html" title="Chapter 30. Boost.Process">
10 <link rel="prev" href="tutorial.html" title="Tutorial">
11 <link rel="next" href="extend.html" title="Extensions">
13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
14 <table cellpadding="2" width="100%"><tr>
15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
16 <td align="center"><a href="../../../index.html">Home</a></td>
17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
20 <td align="center"><a href="../../../more/index.htm">More</a></td>
23 <div class="spirit-nav">
24 <a accesskey="p" href="tutorial.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../process.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="extend.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
28 <a name="boost_process.design"></a><a class="link" href="design.html" title="Design Rationale">Design Rationale</a>
29 </h2></div></div></div>
30 <div class="toc"><dl class="toc">
31 <dt><span class="section"><a href="design.html#boost_process.design.scope">Scope</a></span></dt>
32 <dt><span class="section"><a href="design.html#boost_process.design.interface_style">Interface Style</a></span></dt>
33 <dt><span class="section"><a href="design.html#boost_process.design.arg_cmd_style">Arguments/Command
35 <dt><span class="section"><a href="design.html#boost_process.design.plat_ext">Extensions</a></span></dt>
38 <div class="titlepage"><div><div><h3 class="title">
39 <a name="boost_process.design.scope"></a><a class="link" href="design.html#boost_process.design.scope" title="Scope">Scope</a>
40 </h3></div></div></div>
42 This library is meant to give an wrapper around the different OS-specific
43 methods to launch processes. Its aim is to provide all functionality that
44 is available on those systems and allow the user to do all related things,
45 which require using the OS APIs.
48 <span class="bold"><strong>This library does not try to provide a full library
49 for everything process related</strong></span> In many discussions the proposal
50 was made to build boost.process into a DSEL <a href="#ftn.boost_process.design.scope.f0" class="footnote" name="boost_process.design.scope.f0"><sup class="footnote">[29]</sup></a> of some sort. This is not the goal, it rather provides the facilities
51 to build such a DSEL-Library on top of it. Therefore the library also does
52 <span class="bold"><strong>not</strong></span> force any particular use (such as only
53 asynchronous communication) on its user. It rather could be integrated with
58 <div class="titlepage"><div><div><h3 class="title">
59 <a name="boost_process.design.interface_style"></a><a class="link" href="design.html#boost_process.design.interface_style" title="Interface Style">Interface Style</a>
60 </h3></div></div></div>
62 Boost.Process does use a very particular style when constructing a process.
63 This is because a process holds many properties, which are not members of
64 the actual child class. Those properties are in many cases not accessible
65 by the father process, for example when using environments. Here the child
66 process can modify its own environment, but there is no way for the father
67 process to know. That means, that a child process has properties that cannot
71 This now leads to the two styles supported and mixed by this library. Overloading
72 and properties. Consider that you may want to launch a process passing a
73 number of arguments. This is supported in both styles, and would look like
78 <pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"gcc"</span><span class="special">,</span> <span class="string">"--version"</span><span class="special">);</span> <span class="comment">//overloading</span>
79 <span class="identifier">system</span><span class="special">(</span><span class="string">"gcc"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">={</span><span class="string">"--version"</span><span class="special">});</span> <span class="comment">//property style.</span>
84 Both styles can also be mixed in some cases.
88 <pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"gcc"</span><span class="special">,</span> <span class="string">"-c"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">+={</span><span class="string">"main.cpp"</span><span class="special">});</span>
93 In the following section the avaible styles will be described. Note that
94 the overload style is implemented via type traits, so the types will be listed.
96 <div class="caution"><table border="0" summary="Caution">
98 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td>
99 <th align="left">Caution</th>
101 <tr><td align="left" valign="top"><p>
102 There is no guarantee in which order the arguments will be applied! There
103 is however a guarantee for arguments belonging together, i.e. the string
104 argument and the args property will be evaluated in the order given.
108 <div class="section">
109 <div class="titlepage"><div><div><h3 class="title">
110 <a name="boost_process.design.arg_cmd_style"></a><a class="link" href="design.html#boost_process.design.arg_cmd_style" title="Arguments/Command Style">Arguments/Command
112 </h3></div></div></div>
114 When passing arguments to the process, two styles are provided, the cmd-style
115 and the exe-/args-style.
118 The cmd style will interpret the string as a sequence of the exe and arguments
119 and parse them as such, while the exe-/args-style will interpret each string
123 <a name="boost_process.design.arg_cmd_style.id"></a><p class="title"><b>Table 30.1. Cmd vs Exe/Args</b></p>
124 <div class="table-contents"><table class="table" summary="Cmd vs Exe/Args">
160 {"\"gcc --version\""}
166 <br class="table-break"><p>
167 When using the overloading variant, a single string will result in a cmd
168 interpretation, several strings will yield a exe-args interpretation. Both
169 version can be set explicitly:
173 <pre class="programlisting"><span class="identifier">system</span><span class="special">(</span><span class="string">"grep -c false /etc/passwd"</span><span class="special">);</span> <span class="comment">//cmd style</span>
174 <span class="identifier">system</span><span class="special">(</span><span class="string">"grep"</span><span class="special">,</span> <span class="string">"-c"</span><span class="special">,</span> <span class="string">"false"</span><span class="special">,</span> <span class="string">"/etc/passwd"</span><span class="special">);</span> <span class="comment">//exe-/args-</span>
176 <span class="identifier">system</span><span class="special">(</span><span class="identifier">cmd</span><span class="special">=</span><span class="string">"grep -c false /etc/passwd"</span><span class="special">);</span> <span class="comment">//cmd style</span>
177 <span class="identifier">system</span><span class="special">(</span><span class="identifier">exe</span><span class="special">=</span><span class="string">"grep"</span><span class="special">,</span> <span class="identifier">args</span><span class="special">={</span><span class="string">"-c"</span><span class="special">,</span> <span class="string">"false"</span><span class="special">,</span> <span class="string">"/etc/passwd"</span><span class="special">});</span> <span class="comment">//exe-/args-</span>
181 <div class="note"><table border="0" summary="Note">
183 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
184 <th align="left">Note</th>
186 <tr><td align="left" valign="top"><p>
187 If a '"' sign is used in the argument style, it will be passed as
188 part of the argument. If the same effect it wanted with the cmd syntax,
189 it ought to be escaped, i.e. '\"'.
192 <div class="note"><table border="0" summary="Note">
194 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
195 <th align="left">Note</th>
197 <tr><td align="left" valign="top"><p>
198 The <code class="computeroutput"><span class="identifier">PATH</span></code> variable will
199 automatically be searched in the command style, but the one of the launching
200 process, not the one passed to the child process.
204 <div class="section">
205 <div class="titlepage"><div><div><h3 class="title">
206 <a name="boost_process.design.plat_ext"></a><a class="link" href="design.html#boost_process.design.plat_ext" title="Extensions">Extensions</a>
207 </h3></div></div></div>
209 The simplest form to extend functionality is to provide another handler,
210 which will be called on the respective events on process launching. The names
213 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
214 <li class="listitem">
215 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">process</span><span class="special">::</span><span class="identifier">on_setup</span></code>
217 <li class="listitem">
218 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">process</span><span class="special">::</span><span class="identifier">on_error</span></code>
220 <li class="listitem">
221 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">process</span><span class="special">::</span><span class="identifier">on_success</span></code>
229 <pre class="programlisting"><span class="identifier">child</span> <span class="identifier">c</span><span class="special">(</span><span class="string">"ls"</span><span class="special">,</span> <span class="identifier">on_setup</span><span class="special">([](){</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"On Setup"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;});</span>
233 <div class="note"><table border="0" summary="Note">
235 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
236 <th align="left">Note</th>
238 <tr><td align="left" valign="top"><p>
239 On posix all those callbacks will be handled by this process, not the created
240 one. This is different for the posix extensions, which can be executed
241 on the forked process.
245 <div class="footnotes">
246 <br><hr style="width:100; text-align:left;margin-left: 0">
247 <div id="ftn.boost_process.design.scope.f0" class="footnote"><p><a href="#boost_process.design.scope.f0" class="para"><sup class="para">[29] </sup></a>
248 Domain Specific Embedded Language
252 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
253 <td align="left"></td>
254 <td align="right"><div class="copyright-footer">Copyright © 2006-2012 Julio M. Merino Vidal, Ilya Sokolov,
255 Felipe Tanus, Jeff Flinn, Boris Schaeling<br>Copyright © 2016 Klemens D. Morgenstern<p>
256 Distributed under the Boost Software License, Version 1.0. (See accompanying
257 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
262 <div class="spirit-nav">
263 <a accesskey="p" href="tutorial.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../process.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="extend.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>