diff options
Diffstat (limited to 'boost/process/io.hpp')
-rw-r--r-- | boost/process/io.hpp | 551 |
1 files changed, 551 insertions, 0 deletions
diff --git a/boost/process/io.hpp b/boost/process/io.hpp new file mode 100644 index 0000000000..85a143ca31 --- /dev/null +++ b/boost/process/io.hpp @@ -0,0 +1,551 @@ +// Copyright (c) 2016 Klemens D. Morgenstern
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ +#ifndef BOOST_PROCESS_IO_HPP_
+#define BOOST_PROCESS_IO_HPP_
+ +#include <iosfwd>
+#include <cstdio>
+#include <functional>
+#include <utility>
+#include <boost/process/detail/config.hpp>
+#include <boost/process/pipe.hpp>
+ +#include <future>
+ +#if defined(BOOST_POSIX_API)
+#include <boost/process/detail/posix/asio_fwd.hpp>
+#include <boost/process/detail/posix/close_in.hpp>
+#include <boost/process/detail/posix/close_out.hpp>
+#include <boost/process/detail/posix/null_in.hpp>
+#include <boost/process/detail/posix/null_out.hpp>
+#include <boost/process/detail/posix/file_in.hpp>
+#include <boost/process/detail/posix/file_out.hpp>
+#include <boost/process/detail/posix/pipe_in.hpp>
+#include <boost/process/detail/posix/pipe_out.hpp>
+#elif defined(BOOST_WINDOWS_API)
+#include <boost/process/detail/windows/asio_fwd.hpp>
+#include <boost/process/detail/windows/close_in.hpp>
+#include <boost/process/detail/windows/close_out.hpp>
+#include <boost/process/detail/windows/null_in.hpp>
+#include <boost/process/detail/windows/null_out.hpp>
+#include <boost/process/detail/windows/file_in.hpp>
+#include <boost/process/detail/windows/file_out.hpp>
+#include <boost/process/detail/windows/pipe_in.hpp>
+#include <boost/process/detail/windows/pipe_out.hpp>
+#endif
+ +/** \file boost/process/io.hpp
+ *
+ * Header which provides the io properties. It provides the following properties:
+ *
+\xmlonly
+<programlisting>
+namespace boost {
+ namespace process {
+ <emphasis>unspecified</emphasis> <globalname alt="boost::process::close">close</globalname>;
+ <emphasis>unspecified</emphasis> <globalname alt="boost::process::null">null</globalname>;
+ <emphasis>unspecified</emphasis> <globalname alt="boost::process::std_in">std_in</globalname>;
+ <emphasis>unspecified</emphasis> <globalname alt="boost::process::std_out">std_out</globalname>;
+ <emphasis>unspecified</emphasis> <globalname alt="boost::process::std_err">std_err</globalname>;
+ }
+}
+</programlisting>
+\endxmlonly
+ +\par File I/O
+ +The library allows full redirection of streams to files as shown below.
+ +\code{.cpp}
+boost::filesystem::path log = "my_log_file.txt";
+boost::filesystem::path input = "input.txt";
+boost::filesystem::path output = "output.txt";
+system("my_prog", std_out>output, std_in<input, std_err>log);
+\endcode
+ +\par Synchronous Pipe I/O
+ +Another way is to communicate through pipes.
+ +\code{.cpp}
+pstream str;
+child c("my_prog", std_out > str);
+ +int i;
+str >> i;
+\endcode
+ +Note that the pipe may also be used between several processes, like this:
+ +\code{.cpp}
+pipe p;
+child c1("nm", "a.out", std_out>p);
+child c2("c++filt", std_in<p);
+\endcode
+ +\par Asynchronous I/O
+ +Utilizing `boost.asio` asynchronous I/O is provided.
+ +\code
+boost::asio::io_service ios;
+std::future<std::string> output;
+system("ls", std_out > output, ios);
+ +auto res = fut.get();
+\endcode
+ +\note `boost/process/asnyc.hpp` must also be included for this to work.
+ +\par Closing
+ +Stream can be closed, so nothing can be read or written.
+ +\code{.cpp}
+system("foo", std_in.close());
+\endcode
+ +\par Null
+ +Streams can be redirected to null, which means, that written date will be
+discarded and read data will only contain `EOF`.
+ +\code{.cpp}
+system("b2", std_out > null);
+\endcode
+ + *
+ */
+ +namespace boost { namespace process { namespace detail {
+ + +template<typename T> using is_streambuf = typename std::is_same<T, boost::asio::streambuf>::type;
+template<typename T> using is_const_buffer =
+ std::integral_constant<bool,
+ std::is_same< boost::asio::const_buffer, T>::value |
+ std::is_base_of<boost::asio::const_buffer, T>::value
+ >;
+template<typename T> using is_mutable_buffer =
+ std::integral_constant<bool,
+ std::is_same< boost::asio::mutable_buffer, T>::value |
+ std::is_base_of<boost::asio::mutable_buffer, T>::value
+ >;
+ + +struct null_t {constexpr null_t() {}};
+struct close_t;
+ +template<class>
+struct std_in_
+{
+ constexpr std_in_() {}
+ + api::close_in close() const {return api::close_in(); }
+ api::close_in operator=(const close_t &) const {return api::close_in();}
+ api::close_in operator<(const close_t &) const {return api::close_in();}
+ + api::null_in null() const {return api::null_in();}
+ api::null_in operator=(const null_t &) const {return api::null_in();}
+ api::null_in operator<(const null_t &) const {return api::null_in();}
+ + api::file_in operator=(const boost::filesystem::path &p) const {return p;}
+ api::file_in operator=(const std::string & p) const {return p;}
+ api::file_in operator=(const std::wstring &p) const {return p;}
+ api::file_in operator=(const char * p) const {return p;}
+ api::file_in operator=(const wchar_t * p) const {return p;}
+ + api::file_in operator<(const boost::filesystem::path &p) const {return p;}
+ api::file_in operator<(const std::string &p) const {return p;}
+ api::file_in operator<(const std::wstring &p) const {return p;}
+ api::file_in operator<(const char*p) const {return p;}
+ api::file_in operator<(const wchar_t * p) const {return p;}
+ + api::file_in operator=(FILE * f) const {return f;}
+ api::file_in operator<(FILE * f) const {return f;}
+ + template<typename Char, typename Traits> api::pipe_in operator=(basic_pipe<Char, Traits> & p) const {return p;}
+ template<typename Char, typename Traits> api::pipe_in operator<(basic_pipe<Char, Traits> & p) const {return p;}
+ template<typename Char, typename Traits> api::pipe_in operator=(basic_opstream<Char, Traits> & p) const {return p.pipe();}
+ template<typename Char, typename Traits> api::pipe_in operator<(basic_opstream<Char, Traits> & p) const {return p.pipe();}
+ template<typename Char, typename Traits> api::pipe_in operator=(basic_pstream <Char, Traits> & p) const {return p.pipe();}
+ template<typename Char, typename Traits> api::pipe_in operator<(basic_pstream <Char, Traits> & p) const {return p.pipe();}
+ + api::async_pipe_in operator=(async_pipe & p) const {return p;}
+ api::async_pipe_in operator<(async_pipe & p) const {return p;}
+ + template<typename T, typename = typename std::enable_if<
+ is_const_buffer<T>::value || is_mutable_buffer<T>::value
+ >::type>
+ api::async_in_buffer<const T> operator=(const T & buf) const {return buf;}
+ template<typename T, typename = typename std::enable_if<is_streambuf<T>::value>::type >
+ api::async_in_buffer<T> operator=(T & buf) const {return buf;}
+ + template<typename T, typename = typename std::enable_if<
+ is_const_buffer<T>::value || is_mutable_buffer<T>::value
+ >::type>
+ api::async_in_buffer<const T> operator<(const T & buf) const {return buf;}
+ template<typename T, typename = typename std::enable_if<is_streambuf<T>::value>::type >
+ api::async_in_buffer<T> operator<(T & buf) const {return buf;}
+ +};
+ +//-1 == empty.
+//1 == stdout
+//2 == stderr
+template<int p1, int p2 = -1>
+struct std_out_
+{
+ constexpr std_out_() {}
+ + api::close_out<p1,p2> close() const {return api::close_out<p1,p2>(); }
+ api::close_out<p1,p2> operator=(const close_t &) const {return api::close_out<p1,p2>();}
+ api::close_out<p1,p2> operator>(const close_t &) const {return api::close_out<p1,p2>();}
+ + api::null_out<p1,p2> null() const {return api::null_out<p1,p2>();}
+ api::null_out<p1,p2> operator=(const null_t &) const {return api::null_out<p1,p2>();}
+ api::null_out<p1,p2> operator>(const null_t &) const {return api::null_out<p1,p2>();}
+ + api::file_out<p1,p2> operator=(const boost::filesystem::path &p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator=(const std::string &p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator=(const std::wstring &p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator=(const char * p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator=(const wchar_t * p) const {return api::file_out<p1,p2>(p);}
+ + api::file_out<p1,p2> operator>(const boost::filesystem::path &p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator>(const std::string &p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator>(const std::wstring &p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator>(const char * p) const {return api::file_out<p1,p2>(p);}
+ api::file_out<p1,p2> operator>(const wchar_t * p) const {return api::file_out<p1,p2>(p);}
+ + api::file_out<p1,p2> operator=(FILE * f) const {return f;}
+ api::file_out<p1,p2> operator>(FILE * f) const {return f;}
+ + template<typename Char, typename Traits> api::pipe_out<p1,p2> operator=(basic_pipe<Char, Traits> & p) const {return p;}
+ template<typename Char, typename Traits> api::pipe_out<p1,p2> operator>(basic_pipe<Char, Traits> & p) const {return p;}
+ template<typename Char, typename Traits> api::pipe_out<p1,p2> operator=(basic_ipstream<Char, Traits> & p) const {return p.pipe();}
+ template<typename Char, typename Traits> api::pipe_out<p1,p2> operator>(basic_ipstream<Char, Traits> & p) const {return p.pipe();}
+ template<typename Char, typename Traits> api::pipe_out<p1,p2> operator=(basic_pstream <Char, Traits> & p) const {return p.pipe();}
+ template<typename Char, typename Traits> api::pipe_out<p1,p2> operator>(basic_pstream <Char, Traits> & p) const {return p.pipe();}
+ + api::async_pipe_out<p1, p2> operator=(async_pipe & p) const {return p;}
+ api::async_pipe_out<p1, p2> operator>(async_pipe & p) const {return p;}
+ + api::async_out_buffer<p1, p2, const asio::mutable_buffer> operator=(const asio::mutable_buffer & buf) const {return buf;}
+ api::async_out_buffer<p1, p2, const asio::mutable_buffers_1> operator=(const asio::mutable_buffers_1 & buf) const {return buf;}
+ api::async_out_buffer<p1, p2, asio::streambuf> operator=(asio::streambuf & os) const {return os ;}
+ + api::async_out_buffer<p1, p2, const asio::mutable_buffer> operator>(const asio::mutable_buffer & buf) const {return buf;}
+ api::async_out_buffer<p1, p2, const asio::mutable_buffers_1> operator>(const asio::mutable_buffers_1 & buf) const {return buf;}
+ api::async_out_buffer<p1, p2, asio::streambuf> operator>(asio::streambuf & os) const {return os ;}
+ + api::async_out_future<p1,p2, std::string> operator=(std::future<std::string> & fut) const { return fut;}
+ api::async_out_future<p1,p2, std::string> operator>(std::future<std::string> & fut) const { return fut;}
+ api::async_out_future<p1,p2, std::vector<char>> operator=(std::future<std::vector<char>> & fut) const { return fut;}
+ api::async_out_future<p1,p2, std::vector<char>> operator>(std::future<std::vector<char>> & fut) const { return fut;}
+ + template<int pin, typename = typename std::enable_if<
+ (((p1 == 1) && (pin == 2)) ||
+ ((p1 == 2) && (pin == 1)))
+ && (p2 == -1)>::type>
+ constexpr std_out_<1, 2> operator& (const std_out_<pin>&) const
+ {
+ return std_out_<1, 2> ();
+ }
+ +};
+ +struct close_t
+{
+ constexpr close_t() {}
+ template<int T, int U>
+ api::close_out<T,U> operator()(std_out_<T,U>) {return api::close_out<T,U>();}
+};
+ + + +}
+///This constant is a utility to allow syntax like `std_out > close` for closing I/O streams.
+constexpr boost::process::detail::close_t close;
+///This constant is a utility to redirect streams to the null-device.
+constexpr boost::process::detail::null_t null;
+ +/**
+This property allows to set the input stream for the child process.
+ +\section stdin_details Details
+ +\subsection stdin_file 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:
+ +\code{.cpp}
+system("ls", std_in < stdin);
+\endcode
+ +\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
+ +\code{.cpp}
+std_in < file;
+std_in = file;
+\endcode
+ +\subsection stdin_pipe Pipe Input
+ +As explained in the corresponding section, the boost.process library provides a
+@ref boost::process::async_pipe "async_pipe" class which can be
+used to communicate with child processes.
+ +\note Technically the @ref boost::process::async_pipe "async_pipe"
+works synchronous here, since no asio implementation is used by the library here.
+The async-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:
+ +\code{.cpp}
+std_in < pipe;
+std_in = pipe;
+\endcode
+ +Where the valid types for `pipe` are the following:
+ + - `basic_pipe`
+ - `async_pipe`
+ - `basic_opstream`
+ - `basic_pstream`
+ +Note that the pipe may also be used between several processes, like this:
+ +\code{.cpp}
+pipe p;
+child c1("nm", "a.out", std_out>p);
+child c2("c++filt", std_in<p);
+\endcode
+ +\subsection stdin_async_pipe Asynchronous Pipe Input
+ +Asynchronous Pipe I/O classifies communication which has automatically handling
+of the asynchronous 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::const_buffer` \xmlonly <footnote><para> Constructed with <code>boost::asio::buffer</code></para></footnote> \endxmlonly
+ - `boost::asio::mutable_buffer` \xmlonly <footnote><para> Constructed with <code>boost::asio::buffer</code></para></footnote> \endxmlonly
+ - `boost::asio::streambuf`
+ +Valid expressions with pipes are these:
+ +\code{.cpp}
+std_in < buffer;
+std_in = buffer;
+std_out > buffer;
+std_out = buffer;
+std_err > buffer;
+std_err = buffer;
+(std_out & std_err) > buffer;
+(std_out & std_err) = buffer;
+\endcode
+ +\note It is also possible to get a future for std_in, by chaining another `std::future<void>` onto it,
+so you can wait for the input to be completed. It looks like this:
+\code{.cpp}
+std::future<void> fut;
+boost::asio::io_service ios;
+std::string data;
+child c("prog", std_in < buffer(data) > fut, ios);
+fut.get();
+\endcode
+ + +\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.
+ + +\subsection stdin_close Close
+ +The input stream can be closed, so it cannot be read from. This will lead to an error when attempted.
+ +This can be achieved by the following syntax.
+ +\code{.cpp}
+std_in < close;
+std_in = close;
+std_in.close();
+\endcode
+ +\subsection stdin_null Null
+ +The input stream can be redirected to read from the null-device, which means that only `EOF` is read.
+ +The syntax to achieve that has the following variants:
+ +\code{.cpp}
+std_in < null;
+std_in = null;
+std_in.null();
+\endcode
+ +*/
+ +constexpr boost::process::detail::std_in_<void> std_in;
+ +/**
+This property allows to set the output stream for the child process.
+ +\note The Semantic is the same as for \xmlonly <globalname alt="boost::process::std_err">std_err</globalname> \endxmlonly
+ +\note `std_err` and `std_out` can be combined into one stream, with the `operator &`, i.e. `std_out & std_err`.
+ +\section stdout_details Details
+ +\subsection stdout_file 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:
+ +\code{.cpp}
+system("ls", std_out < stdin);
+\endcode
+ +\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
+ +\code{.cpp}
+std_out < file;
+std_out = file;
+\endcode
+ +\subsection stdout_pipe Pipe Output
+ +As explained in the corresponding section, the boost.process library provides a
+@ref boost::process::async_pipe "async_pipe" class which can be
+used to communicate with child processes.
+ +\note Technically the @ref boost::process::async_pipe "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:
+ +\code{.cpp}
+std_out > pipe;
+std_out = pipe;
+\endcode
+ +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:
+ +\code{.cpp}
+pipe p;
+child c1("nm", "a.out", std_out>p);
+child c2("c++filt", std_in<p);
+\endcode
+ +\subsection stdout_async_pipe 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` \xmlonly <footnote><para> Constructed with <code>boost::asio::buffer</code></para></footnote> \endxmlonly
+ - `boost::asio::streambuf`
+ - `std::future<std::vector<char>>`
+ - `std::future<std::string>`
+ +Valid expressions with pipes are these:
+ +\code{.cpp}
+std_out > buffer;
+std_out = buffer;
+std_err > buffer;
+std_err = buffer;
+(std_out & std_err) > buffer;
+(std_out & std_err) = buffer;
+\endcode
+ +\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.
+ + +\subsection stdout_close 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.
+ +\code{.cpp}
+std_out > close;
+std_out = close;
+std_out.close();
+\endcode
+ +\subsection stdout_null 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:
+ +\code{.cpp}
+std_out > null;
+std_out = null;
+std_out.null();
+\endcode
+ +*/
+ +constexpr boost::process::detail::std_out_<1> std_out;
+/**This property allows setting the `stderr` stream. The semantic and syntax is the same as for
+ * \xmlonly <globalname alt="boost::process::std_out">std_out</globalname> \endxmlonly .
+ */
+constexpr boost::process::detail::std_out_<2> std_err;
+ +}}
+#endif /* INCLUDE_BOOST_PROCESS_IO_HPP_ */
|