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

This is an the documentation for an old version of boost. Click here for the latest Boost documentation.

Daytime.1 - A synchronous TCP daytime client

This tutorial program shows how to use asio to implement a client application with TCP.

We start by including the necessary header files.

#include <iostream>
#include <boost/array.hpp>
#include <boost/asio.hpp>

The purpose of this application is to access a daytime service, so we need the user to specify the server.

using boost::asio::ip::tcp;

int main(int argc, char* argv[])
    if (argc != 2)
      std::cerr << "Usage: client <host>" << std::endl;
      return 1;

All programs that use asio need to have at least one io_service object.

    boost::asio::io_service io_service;

We need to turn the server name that was specified as a parameter to the application, into a TCP endpoint. To do this we use an ip::tcp::resolver object.

    tcp::resolver resolver(io_service);

A resolver takes a query object and turns it into a list of endpoints. We construct a query using the name of the server, specified in argv[1], and the name of the service, in this case "daytime".

    tcp::resolver::query query(argv[1], "daytime");

The list of endpoints is returned using an iterator of type ip::tcp::resolver::iterator. A default constructed ip::tcp::resolver::iterator object is used as the end iterator.

    tcp::resolver::iterator endpoint_iterator = resolver.resolve(query);
    tcp::resolver::iterator end;

Now we create and connect the socket. The list of endpoints obtained above may contain both IPv4 and IPv6 endpoints, so we need to try each of them until we find one that works. This keeps the client program independent of a specific IP version.

    tcp::socket socket(io_service);
    boost::system::error_code error = boost::asio::error::host_not_found;
    while (error && endpoint_iterator != end)
      socket.connect(*endpoint_iterator++, error);
    if (error)
      throw boost::system::system_error(error);

The connection is open. All we need to do now is read the response from the daytime service.

We use a boost::array to hold the received data. The boost::asio::buffer() function automatically determines the size of the array to help prevent buffer overruns. Instead of a boost::array, we could have used a char [] or std::vector.

    for (;;)
      boost::array<char, 128> buf;
      boost::system::error_code error;

      size_t len = socket.read_some(boost::asio::buffer(buf), error);

When the server closes the connection, the ip::tcp::socket::read_some() function will exit with the boost::asio::error::eof error, which is how we know to exit the loop.

      if (error == boost::asio::error::eof)
        break; // Connection closed cleanly by peer.
      else if (error)
        throw boost::system::system_error(error); // Some other error.

      std::cout.write(, len);

Finally, handle any exceptions that may have been thrown.

  catch (std::exception& e)
    std::cerr << e.what() << std::endl;

See the full source listing

Return to the tutorial index

Next: Daytime.2 - A synchronous TCP daytime server