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

This is the documentation for a snapshot of the develop branch, built from commit adcd4c09f0.
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 = boost::asio::any_io_executor> 
struct basic_popen :
  public boost::process::v2::basic_process< boost::asio::any_io_executor >
{
  // types
  typedef Executor                                     executor_type;  // The executor of the process. 
  typedef boost::asio::basic_writable_pipe< Executor > stdin_type;     // The type used for stdin on the parent process side. 
  typedef boost::asio::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. 
  };

  // construct/copy/destruct
  basic_popen(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 &, boost::asio::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 &, boost::asio::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 &, boost::asio::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 &, boost::asio::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 &, boost::asio::execution_context & >::value, const filesystem::path & >::type, 
                         Args &&, Inits &&...);
  basic_popen & operator=(basic_popen &&) = default;

  // public member functions
  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, 
           BOOST_ASIO_COMPLETION_TOKEN_FOR(void(boost::system::error_code, std::size_t)) WriteToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type) > 
    deduced async_write_some(const ConstBufferSequence &, 
                             BOOST_ASIO_MOVE_ARG(WriteToken) token DEFAULT(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, 
           BOOST_ASIO_COMPLETION_TOKEN_FOR(void(boost::system::error_code, std::size_t)) ReadToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type) > 
    deduced async_read_some(const MutableBufferSequence &, 
                            BOOST_ASIO_MOVE_ARG(ReadToken) token DEFAULT(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 construct/copy/destruct

  1. basic_popen(basic_popen &&) = default;
    Move construct a popen. 
  2. template<typename Executor1> basic_popen(basic_popen< Executor1 > && lhs);
    Move construct a popen and change the executor type. 
  3. explicit basic_popen(executor_type exec);
    Create a closed process handle. 
  4. template<typename ExecutionContext> 
  explicit basic_popen(ExecutionContext & context, 
                       typename std::enable_if< is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
    Create a closed process handle. 
  5. 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. 
  6. 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. 
  7. 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. 
  8. 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. 
  9. template<typename ExecutionContext, typename ... Inits> 
  explicit basic_popen(ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::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. 
  10. template<typename Launcher, typename ExecutionContext, typename ... Inits> 
  explicit basic_popen(Launcher && launcher, ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::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 ExecutionContext, typename Args, typename ... Inits> 
  explicit basic_popen(ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::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. 
  12. template<typename Launcher, typename ExecutionContext, typename Args, 
         typename ... Inits> 
  explicit basic_popen(Launcher && launcher, ExecutionContext & context, 
                       typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::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. basic_popen & operator=(basic_popen &&) = default;
    Move assign a popen.

basic_popen public member functions

  1. stdin_type & get_stdin();
    Get the stdin pipe. 
  2. stdout_type & get_stdout();
    Get the stdout pipe. 
  3. const stdin_type & get_stdin() const;
    Get the stdin pipe. 
  4. const stdout_type & get_stdout() const;
    Get the stdout pipe. 
  5. 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. 
  6. 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.

    		 
  7. template<typename ConstBufferSequence, 
         BOOST_ASIO_COMPLETION_TOKEN_FOR(void(boost::system::error_code, std::size_t)) WriteToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type) > 
  deduced async_write_some(const ConstBufferSequence & buffers, 
                           BOOST_ASIO_MOVE_ARG(WriteToken) token DEFAULT(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.

    		 
  8. 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. 
  9. 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.

    		 
  10. template<typename MutableBufferSequence, 
         BOOST_ASIO_COMPLETION_TOKEN_FOR(void(boost::system::error_code, std::size_t)) ReadToken BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type) > 
  deduced async_read_some(const MutableBufferSequence & buffers, 
                          BOOST_ASIO_MOVE_ARG(ReadToken) token DEFAULT(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.
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