1[section:design Design Rationale] 2[section Scope] 3This library is meant to give a wrapper around the different OS-specific methods 4to launch processes. Its aim is to provide all functionality that is available on 5those systems and allow the user to do all related things, which require using the OS APIs. 6 7[*This library does not try to provide a full library for everything process related.] 8In many discussions the proposal was made to build boost.process into a DSEL [footnote Domain Specific Embedded Language] of some sort. 9This is not the goal, it rather provides the facilities to build such a DSEL-library on top of it. 10Therefore the library also does [*not] force any particular use (such as only asynchronous communication) on its user. 11It rather could be integrated with such a library. 12 13[endsect] 14[section Interface Style] 15 16Boost.Process does use a very particular style when constructing a process. 17This is because a process holds many properties, which are not members of the actual child class. 18Those properties are in many cases not accessible by the father process, for example when using environments. 19Here the child process can modify its own environment, but there is no way for the father process to know. 20That means, that a child process has properties that cannot be accessed in C++. 21 22This now leads to the two styles supported and mixed by this library. Overloading and properties. 23Consider that you may want to launch a process passing a number of arguments. This is supported in both styles, and would look like this: 24 25``` 26system("gcc", "--version"); //overloading 27system("gcc", args={"--version"}); //property style. 28``` 29 30Both styles can also be mixed in some cases. 31 32``` 33system("gcc", "-c", args+={"main.cpp"}); 34``` 35 36In the following section the available styles will be described. Note that the 37overload style is implemented via type traits, so the types will be listed. 38 39[caution There is no guarantee in which order the arguments will be applied! 40There is however a guarantee for arguments belonging together, i.e. the string 41argument and the args property will be evaluated in the order given.] 42 43[endsect] 44[section:arg_cmd_style Arguments/Command Style] 45 46When passing arguments to the process, two styles are provided, the cmd-style and the exe-/args-style. 47 48The 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 49interpret each string as an argument. 50 51[table:id Cmd vs Exe/Args 52 [[String] [Cmd] [Exe/Args]] 53 [["gcc --version"] [{"gcc", "--version"}] [{"\\"gcc --version\\""}]] 54] 55 56When using the overloading variant, a single string will result in a cmd interpretation, 57several strings will yield a exe-args interpretation. Both versions can be set explicitly: 58 59``` 60system("grep -c false /etc/passwd"); //cmd style 61system("grep", "-c", "false", "/etc/passwd"); //exe-/args- 62 63system(cmd="grep -c false /etc/passwd"); //cmd style 64system(exe="grep", args={"-c", "false", "/etc/passwd"}); //exe-/args- 65``` 66 67[note If a '"' sign is used in the argument style, it will be passed as part of the argument. 68If the same effect is wanted with the cmd syntax, it ought to be escaped, i.e. '\\\"'. ] 69[note The `PATH` variable will automatically be searched in the command style, 70but the one of the launching process, not the one passed to the child process.] 71[endsect] 72 73[section:plat_ext Extensions] 74 75The simplest form to extend functionality is to provide another handler, which 76will be called on the respective events on process launching. The names are: 77 78*`boost::process::on_setup` 79*`boost::process::on_error` 80*`boost::process::on_success` 81 82 83As an example: 84 85``` 86child c("ls", on_setup([](){cout << "On Setup" << endl;}); 87``` 88 89 90[note On posix all those callbacks will be handled by this process, not the created one. 91This is different for the posix extensions, which can be executed on the forked process.] 92[endsect] 93 94[endsect] 95