Using Boost.Asio

| Home | Libraries | People | FAQ | More

## Using Boost.Asio

#### Supported Platforms

The following platforms and compilers have been tested:

- Win32 and Win64 using Visual C++ 7.1 and Visual C++ 8.0.
- Win32 using MinGW.
- Win32 using Cygwin. (`__USE_W32_SOCKETS` must be defined.)
- Linux (2.4 or 2.6 kernels) using g++ 3.3 or later.
- Solaris using g++ 3.3 or later.
- Mac OS X 10.4 using g++ 3.3 or later.

The following platforms may also work:

- AIX 5.3 using XL C/C++ v9.
- HP-UX 11i v3 using patched aC++ A.06.14.
- QNX Neutrino 6.3 using g++ 3.3 or later.
- Solaris using Sun Studio 11 or later.
- Tru64 v5.1 using Compaq C++ v7.1.
- Win32 using Borland C++ 5.9.2

#### Dependencies

The following libraries must be available in order to link programs that use Boost.Asio:

- Boost.System for the `boost::system::error_code` and `boost::system::system_error` classes.
- Boost.Regex (optional) if you use any of the `read_until()` or `async_read_until()` overloads that take a `boost::regex` parameter.
- OpenSSL (optional) if you use Boost.Asio's SSL support.

Furthermore, some of the examples also require the Boost.Thread, Boost.Date_Time or Boost.Serialization libraries.

| Note
With MSVC or Borland C++ you may want to add `-DBOOST_DATE_TIME_NO_LIB` and `-DBOOST_REGEX_NO_LIB` to your project settings to disable autolinking of the Boost.Date_Time and Boost.Regex libraries respectively. Alternatively, you may choose to build these libraries and link to them.

#### Building Boost Libraries

You may build the subset of Boost libraries required to use Boost.Asio and its examples by running the following command from the root of the Boost download package:

    bjam --with-system --with-thread --with-date_time --with-regex --with-serialization stage

This assumes that you have already built `bjam`. Consult the Boost.Build documentation for more details.

#### Macros

The macros listed in the table below may be used to control the behaviour of Boost.Asio.

Macro | Description
--- | ---

`BOOST_ASIO_ENABLE_BUFFER_DEBUGGING`

Enables Boost.Asio's buffer debugging support, which can help identify when invalid buffers are used in read or write operations (e.g. if a std::string object being written is destroyed before the write operation completes).

When using Microsoft Visual C++, this macro is defined automatically if the compiler's iterator debugging support is enabled, unless `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.

When using g++, this macro is defined automatically if standard library debugging is enabled (`_GLIBCXX_DEBUG` is defined), unless `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.

`BOOST_ASIO_DISABLE_BUFFER_DEBUGGING` | Explictly disables Boost.Asio's buffer debugging support.
`BOOST_ASIO_DISABLE_DEV_POLL` | Explicitly disables `/dev/poll` support on Solaris, forcing the use of a `select`-based implementation.
`BOOST_ASIO_DISABLE_EPOLL` | Explicitly disables `epoll` support on Linux, forcing the use of a `select`-based implementation.
`BOOST_ASIO_DISABLE_KQUEUE` | Explicitly disables `kqueue` support on Mac OS X and BSD variants, forcing the use of a `select`-based implementation.
`BOOST_ASIO_DISABLE_IOCP` | Explicitly disables I/O completion ports support on Windows, forcing the use of a `select`-based implementation.
`BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN` | By default, Boost.Asio will automatically define `WIN32_LEAN_AND_MEAN` when compiling for Windows, to minimise the number of Windows SDK header files and features that are included. The presence of `BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN` prevents `WIN32_LEAN_AND_MEAN` from being defined.
`BOOST_ASIO_NO_DEFAULT_LINKED_LIBS` | When compiling for Windows using Microsoft Visual C++ or Borland C++, Boost.Asio will automatically link in the necessary Windows SDK libraries for sockets support (i.e. `ws2_32.lib` and `mswsock.lib`, or `ws2.lib` when building for Windows CE). The `BOOST_ASIO_NO_DEFAULT_LINKED_LIBS` macro prevents these libraries from being linked.
`BOOST_ASIO_SOCKET_STREAMBUF_MAX_ARITY` | Determines the maximum number of arguments that may be passed to the `basic_socket_streambuf` class template's `connect` member function. Defaults to 5.
`BOOST_ASIO_SOCKET_IOSTREAM_MAX_ARITY` | Determines the maximum number of arguments that may be passed to the `basic_socket_iostream` class template's constructor and `connect` member function. Defaults to 5.

`BOOST_ASIO_ENABLE_CANCELIO`

Enables use of the `CancelIo` function on older versions of Windows. If not enabled, calls to `cancel()` on a socket object will always fail with `asio::error::operation_not_supported` when run on Windows XP, Windows Server 2003, and earlier versions of Windows. When running on Windows Vista, Windows Server 2008, and later, the `CancelIoEx` function is always used.

The `CancelIo` function has two issues that should be considered before enabling its use:

* It will only cancel asynchronous operations that were initiated in the current thread.

* It can appear to complete without error, but the request to cancel the unfinished operations may be silently ignored by the operating system. Whether it works or not seems to depend on the drivers that are installed.

For portable cancellation, consider using one of the following alternatives:

* Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP.

* Use the socket object's close() function to simultaneously cancel the outstanding operations and close the socket.