Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Struct template basic_popen

boost::process::v2::basic_popen — A subprocess with automatically assigned pipes.

Synopsis

// In header: <boost/process/v2/popen.hpp>

template<typename Executor = net::any_io_executor> 
struct basic_popen :
  public boost::process::v2::basic_process< net::any_io_executor >
{
  // types
  typedef Executor                             executor_type;  // The executor of the process. 
  typedef net::basic_writable_pipe< Executor > stdin_type;     // The type used for stdin on the parent process side. 
  typedef net::basic_readable_pipe< Executor > stdout_type;    // The type used for stdout on the parent process side. 

  // member classes/structs/unions

  // Rebinds the popen type to another executor.
  template<typename Executor1> 
  struct rebind_executor {
    // types
    typedef basic_popen< Executor1 > other;  // The pipe type when rebound to the specified executor. 
  };

  // public member functions
  basic_popen(basic_popen &&) = default;
  basic_popen & operator=(basic_popen &&) = default;
  template<typename Executor1> basic_popen(basic_popen< Executor1 > &&);
  explicit basic_popen(executor_type);
  template<typename ExecutionContext> 
    explicit basic_popen(ExecutionContext &, 
                         typename std::enable_if< is_convertible< ExecutionContext &, net::execution_context & >::value, void * >::type = nullptr);
  template<typename ... Inits> 
    explicit basic_popen(executor_type, const filesystem::path &, 
                         std::initializer_list< string_view >, Inits &&...);
  template<typename Launcher, typename ... Inits> 
    explicit basic_popen(Launcher &&, executor_type, const filesystem::path &, 
                         std::initializer_list< string_view >, Inits &&...);
  template<typename Args, typename ... Inits> 
    explicit basic_popen(executor_type, const filesystem::path &, Args &&, 
                         Inits &&...);
  template<typename Launcher, typename Args, typename ... Inits> 
    explicit basic_popen(Launcher &&, executor_type, const filesystem::path &, 
                         Args &&, Inits &&...);
  template<typename ExecutionContext, typename ... Inits> 
    explicit basic_popen(ExecutionContext &, 
                         typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type, 
                         std::initializer_list< string_view >, Inits &&...);
  template<typename Launcher, typename ExecutionContext, typename ... Inits> 
    explicit basic_popen(Launcher &&, ExecutionContext &, 
                         typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type, 
                         std::initializer_list< string_view >, Inits &&...);
  template<typename ExecutionContext, typename Args, typename ... Inits> 
    explicit basic_popen(ExecutionContext &, 
                         typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type, 
                         Args &&, Inits &&...);
  template<typename Launcher, typename ExecutionContext, typename Args, 
           typename ... Inits> 
    explicit basic_popen(Launcher &&, ExecutionContext &, 
                         typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type, 
                         Args &&, Inits &&...);
  stdin_type & get_stdin();
  stdout_type & get_stdout();
  const stdin_type & get_stdin() const;
  const stdout_type & get_stdout() const;
  template<typename ConstBufferSequence> 
    std::size_t write_some(const ConstBufferSequence &);
  template<typename ConstBufferSequence> 
    std::size_t write_some(const ConstBufferSequence &, 
                           boost::system::error_code &);
  template<typename ConstBufferSequence, 
           WriteToken = net::default_completion_token_t<executor_type> > 
    auto async_write_some(const ConstBufferSequence &, 
                          WriteToken && = net::default_completion_token_t< executor_type >());
  template<typename MutableBufferSequence> 
    std::size_t read_some(const MutableBufferSequence &);
  template<typename MutableBufferSequence> 
    std::size_t read_some(const MutableBufferSequence &, 
                          boost::system::error_code &);
  template<typename MutableBufferSequence, 
           ReadToken = net::default_completion_token_t<executor_type> > 
    auto async_read_some(const MutableBufferSequence &, 
                         BOOST_ASIO_MOVE_ARG(ReadToken) = net::default_completion_token_t< executor_type >());
};

Description

The purpose os the popen is to provide a convenient way to use the stdin & stdout of a process.

popen proc(executor, find_executable("addr2line"), {argv[0]});
asio::write(proc, asio::buffer("main\n"));
std::string line;
asio::read_until(proc, asio::dynamic_buffer(line), '\n');

Popen can be used as a stream object in other protocols.

basic_popen public member functions

  1. basic_popen(basic_popen &&) = default;
    Move construct a popen. 
  2. basic_popen & operator=(basic_popen &&) = default;
    Move assign a popen. 
  3. template<typename Executor1> basic_popen(basic_popen< Executor1 > && lhs);
    Move construct a popen and change the executor type. 
  4. explicit basic_popen(executor_type exec);
    Create a closed process handle. 
  5. template<typename ExecutionContext> 
  explicit basic_popen(ExecutionContext & context, 
                       typename std::enable_if< is_convertible< ExecutionContext &, net::execution_context & >::value, void * >::type = nullptr);
    Create a closed process handle. 
  6. template<typename ... Inits> 
  explicit basic_popen(executor_type executor, const filesystem::path & exe, 
                       std::initializer_list< string_view > args, 
                       Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  7. template<typename Launcher, typename ... Inits> 
  explicit basic_popen(Launcher && launcher, executor_type executor, 
                       const filesystem::path & exe, 
                       std::initializer_list< string_view > args, 
                       Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  8. template<typename Args, typename ... Inits> 
  explicit basic_popen(executor_type executor, const filesystem::path & exe, 
                       Args && args, Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  9. template<typename Launcher, typename Args, typename ... Inits> 
  explicit basic_popen(Launcher && launcher, executor_type executor, 
                       const filesystem::path & exe, Args && args, 
                       Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  10. template<typename ExecutionContext, typename ... Inits> 
  explicit basic_popen(ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type exe, 
                       std::initializer_list< string_view > args, 
                       Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  11. template<typename Launcher, typename ExecutionContext, typename ... Inits> 
  explicit basic_popen(Launcher && launcher, ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type exe, 
                       std::initializer_list< string_view > args, 
                       Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  12. template<typename ExecutionContext, typename Args, typename ... Inits> 
  explicit basic_popen(ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type exe, 
                       Args && args, Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  13. template<typename Launcher, typename ExecutionContext, typename Args, 
         typename ... Inits> 
  explicit basic_popen(Launcher && launcher, ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, net::execution_context & >::value, const filesystem::path & >::type exe, 
                       Args && args, Inits &&... inits);
    Construct a child from a property list and launch it using the default process launcher. 
  14. stdin_type & get_stdin();
    Get the stdin pipe. 
  15. stdout_type & get_stdout();
    Get the stdout pipe. 
  16. const stdin_type & get_stdin() const;
    Get the stdin pipe. 
  17. const stdout_type & get_stdout() const;
    Get the stdout pipe. 
  18. template<typename ConstBufferSequence> 
  std::size_t write_some(const ConstBufferSequence & buffers);
    Write some data to the pipe.

    This function is used to write data to the pipe. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.

    [Note] Note

    The write_some operation may not transmit all of the data to the peer. Consider using the write function if you need to ensure that all data is written before the blocking operation completes.

    Example. To write a single data buffer use the buffer function as follows: 

    pipe.write_some(boost::asio::buffer(data, size));

    See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

    Parameters:

    buffers

    One or more data buffers to be written to the pipe.

    Returns:

    The number of bytes written.

    Throws:

    		 boost::system::system_error Thrown on failure. An error code of boost::asio::error::eof indicates that the connection was closed by the subprocess. 
  19. template<typename ConstBufferSequence> 
  std::size_t write_some(const ConstBufferSequence & buffers, 
                         boost::system::error_code & ec);
    Write some data to the pipe.

    This function is used to write data to the pipe. The function call will block until one or more bytes of the data has been written successfully, or until an error occurs.

    [Note] Note

    The write_some operation may not transmit all of the data to the subprocess. Consider using the write function if you need to ensure that all data is written before the blocking operation completes.

    Parameters:

    buffers

    One or more data buffers to be written to the pipe.

    ec

    Set to indicate what error occurred, if any.

    Returns:

    The number of bytes written. Returns 0 if an error occurred.

    		 
  20. template<typename ConstBufferSequence, 
         WriteToken = net::default_completion_token_t<executor_type> > 
  auto async_write_some(const ConstBufferSequence & buffers, 
                        WriteToken && token = net::default_completion_token_t< executor_type >());
    Start an asynchronous write.

    This function is used to asynchronously write data to the pipe. It is an initiating function for an asynchronous_operation, and always returns immediately.

    Completion Signature. 

    void(boost::system::error_code, std::size_t)

    [Note] Note

    The write operation may not transmit all of the data to the peer. Consider using the async_write function if you need to ensure that all data is written before the asynchronous operation completes.

    Example. To write a single data buffer use the buffer function as follows: 

    popen.async_write_some(boost::asio::buffer(data, size), handler);

    See the buffer documentation for information on writing multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

    Parameters:

    buffers

    One or more data buffers to be written to the pipe. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.

    token

    The completion_token that will be used to produce a completion handler, which will be called when the write completes. Potential completion tokens include use_future, use_awaitable, yield_context, or a function object with the correct completion signature. The function signature of the completion handler must be: 

     void handler(
  const boost::system::error_code& error, // Result of operation.
  std::size_t bytes_transferred // Number of bytes written.
);

    Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using boost::asio::post().

    		 
  21. template<typename MutableBufferSequence> 
  std::size_t read_some(const MutableBufferSequence & buffers);
    Read some data from the pipe.

    This function is used to read data from the pipe. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

    [Note] Note

    The read_some operation may not read all of the requested number of bytes. Consider using the read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

    Example. To read into a single data buffer use the buffer function as follows: 

    basic_readable_pipe.read_some(boost::asio::buffer(data, size));

    See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

    Parameters:

    buffers

    One or more buffers into which the data will be read.

    Returns:

    The number of bytes read.

    Throws:

    		 boost::system::system_error Thrown on failure. An error code of boost::asio::error::eof indicates that the connection was closed by the peer. 
  22. template<typename MutableBufferSequence> 
  std::size_t read_some(const MutableBufferSequence & buffers, 
                        boost::system::error_code & ec);
    Read some data from the pipe.

    This function is used to read data from the pipe. The function call will block until one or more bytes of data has been read successfully, or until an error occurs.

    [Note] Note

    The read_some operation may not read all of the requested number of bytes. Consider using the read function if you need to ensure that the requested amount of data is read before the blocking operation completes.

    Parameters:

    buffers

    One or more buffers into which the data will be read.

    ec

    Set to indicate what error occurred, if any.

    Returns:

    The number of bytes read. Returns 0 if an error occurred.

    		 
  23. template<typename MutableBufferSequence, 
         ReadToken = net::default_completion_token_t<executor_type> > 
  auto async_read_some(const MutableBufferSequence & buffers, 
                       BOOST_ASIO_MOVE_ARG(ReadToken) token = net::default_completion_token_t< executor_type >());
    Start an asynchronous read.

    This function is used to asynchronously read data from the pipe. It is an initiating function for an asynchronous_operation, and always returns immediately.

    Completion Signature. 

    void(boost::system::error_code, std::size_t)

    [Note] Note

    The read operation may not read all of the requested number of bytes. Consider using the async_read function if you need to ensure that the requested amount of data is read before the asynchronous operation completes.

    Example. To read into a single data buffer use the buffer function as follows: 

    basic_readable_pipe.async_read_some(
    boost::asio::buffer(data, size), handler);

    See the buffer documentation for information on reading into multiple buffers in one go, and how to use it with arrays, boost::array or std::vector.

    Parameters:

    buffers

    One or more buffers into which the data will be read. Although the buffers object may be copied as necessary, ownership of the underlying memory blocks is retained by the caller, which must guarantee that they remain valid until the completion handler is called.

    token

    The completion_token that will be used to produce a completion handler, which will be called when the read completes. Potential completion tokens include use_future, use_awaitable, yield_context, or a function object with the correct completion signature. The function signature of the completion handler must be: 

     void handler(
  const boost::system::error_code& error, // Result of operation.
  std::size_t bytes_transferred // Number of bytes read.
);

    Regardless of whether the asynchronous operation completes immediately or not, the completion handler will not be invoked from within this function. On immediate completion, invocation of the handler will be performed in a manner equivalent to using boost::asio::post().
Copyright © 2006-2012 Julio M. Merino Vidal, Ilya Sokolov, Felipe Tanus, Jeff Flinn, Boris Schaeling
Copyright © 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)

PrevUpHomeNext