Using, Building, and Configuring Asio

Supported Platforms

The following platform and compiler combinations are regularly tested:

Linux using g++ 4.6 or later
Linux using clang 3.4 or later
FreeBSD using g++ 9 or later
macOS using Xcode 10 or later
Win32 using Visual C++ 11.0 (Visual Studio 2012) or later
Win64 using Visual C++ 11.0 (Visual Studio 2012) or later

The following platforms may also work:

AIX
Android
HP-UX
iOS
NetBSD
OpenBSD
QNX Neutrino
Solaris
Tru64
Win32 using MinGW.
Win32 using Cygwin. (__USE_W32_SOCKETS must be defined.)

Dependencies

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

Boost.Coroutine (optional) if you use spawn() to launch coroutines.
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 Asio's SSL support.

Furthermore, some of the examples also require 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.

By default, Asio is a header-only library. However, some developers may prefer to build Asio using separately compiled source code. To do this, add #include <asio/impl/src.hpp> to one (and only one) source file in a program, then build the program with ASIO_SEPARATE_COMPILATION defined in the project/compiler settings. Alternatively, ASIO_DYN_LINK may be defined to build a separately-compiled Asio as part of a shared library.

If using Asio's SSL support, you will also need to add #include <asio/ssl/impl/src.hpp>.

Building the tests and examples on Linux or UNIX

If the boost directory (e.g. the directory called boost_1_34_1) is in the same directory as the asio source kit, then you may configure asio by simply going:

./configure

in the root directory of the asio source kit. Note that configure will always use the most recent boost version it knows about (i.e. 1.34.1) in preference to earlier versions, if there is more than one version present.

If the boost directory is in some other location, then you need to specify this directory when running configure:

./configure --with-boost=path_to_boost

When specifying the boost directory in this way you should ensure that you use an absolute path.

To build the examples, simply run make in the root directory of the asio source kit. To also build and run the unit tests, to confirm that asio is working correctly, run make check.

Building the tests and examples with MSVC

To build using the MSVC 9.0 (or later) command line compiler, perform the following steps in a Command Prompt window:

If you are using a version of boost other than 1.34.1, or if the boost directory (i.e. the directory called boost_1_34_1) is not in the same directory as the asio source kit, then specify the location of boost by running a command similar to set BOOSTDIR=path_to_boost. Ensure that you specify an absolute path.
Change to the asio src directory.
Execute the command nmake -f Makefile.msc.
Execute the command nmake -f Makefile.msc check to run a suite of tests to confirm that asio is working correctly.

Building the tests and examples with MinGW

To build using the MinGW g++ compiler from the command line, perform the following steps in a Command Prompt window:

If you are using a version of boost other than 1.34.1, or if the boost directory (i.e. the directory called boost_1_34_1) is not in the same directory as the asio source kit, then specify the location of boost by running a command similar to set BOOSTDIR=path_to_boost. Ensure that you specify an absolute path using forward slashes (i.e. c:/projects/boost_1_34_1 rather than c:\projects\boost_1_34_1).
Change to the asio src directory.
Execute the command make -f Makefile.mgw.
Execute the command make -f Makefile.mgw check to run a suite of tests to confirm that asio is working correctly.

	Note
	The above instructions do not work when building inside MSYS. If you want to build using MSYS, you should use `export` rather than `set` to specify the location of boost.

Macros

The macros listed in the table below may be used to control the interface, functionality, and behaviour of Asio.

Macro	Description
`ASIO_NO_DEPRECATED`	Disables Asio's deprecated interfaces and functionality. See Networking TS Compatibility for a list of older interfaces that have been deprecated, and their replacements.
`ASIO_NO_TS_EXECUTORS`	Disables Asio's support for the Networking TS executor model. By default, Asio simultaneously supports both Networking TS-style executors, and executors that adhere to the proposed standard executor model. This macro may be used to limit support to the proposed standard executors only. See Proposed Standard Executors for more information.
`ASIO_USE_TS_EXECUTOR_AS_DEFAULT`	Specifies that `any_io_executor` refer to the Networking TS-style polymorphic wrapper. The `any_io_executor` type alias is the default runtime-polymorphic executor for all I/O objects. This type alias points to the `execution::any_executor<>` template with a set of supportable properties specified for use with I/O. This new name may break existing code that directly uses the old Networking TS-style polymorphic wrapper, `executor`. If required for backward compatibility, `ASIO_USE_TS_EXECUTOR_AS_DEFAULT` changes the `any_io_executor` type alias to instead point to the `executor` polymorphic wrapper. See Proposed Standard Executors for more information.
`ASIO_NO_DYNAMIC_BUFFER_V1`	Disables support for the `DynamicBuffer_v1` type requirements. By default, dynamic buffer operations such as `read`, `async_read`, `read_until`, `async_read_until`, `write`, and `async_write` support both the `DynamicBuffer_v1` and the `DynamicBuffer_v2` type requirements for dynamic buffers. When `ASIO_NO_DYNAMIC_BUFFER_V1` is defined, all support for `DynamicBuffer_v1` types and functions is #ifdef-ed out. Support for using `basic_streambuf` with the `read`, `async_read`, `read_until`, `async_read_until`, `write`, and `async_write` functions is also disabled as a consequence.
`ASIO_ENABLE_BUFFER_DEBUGGING`	Enables 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++ 11.0 or later, this macro is defined automatically if the compiler's iterator debugging support is enabled, unless `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 `ASIO_DISABLE_BUFFER_DEBUGGING` has been defined.
`ASIO_DISABLE_BUFFER_DEBUGGING`	Explictly disables Asio's buffer debugging support.
`ASIO_ENABLE_HANDLER_TRACKING`	Enables Asio's Handler Tracking debugging facility.
`ASIO_DISABLE_DEV_POLL`	Explicitly disables `/dev/poll` support on Solaris, forcing the use of a `select`-based implementation.
`ASIO_DISABLE_EPOLL`	Explicitly disables `epoll` support on Linux, forcing the use of a `select`-based implementation.
`ASIO_DISABLE_EVENTFD`	Explicitly disables `eventfd` support on Linux, forcing the use of a pipe to interrupt blocked epoll/select system calls.
`ASIO_DISABLE_KQUEUE`	Explicitly disables `kqueue` support on macOS and BSD variants, forcing the use of a `select`-based implementation.
`ASIO_DISABLE_IOCP`	Explicitly disables I/O completion ports support on Windows, forcing the use of a `select`-based implementation.
`ASIO_DISABLE_THREADS`	Explicitly disables Asio's threading support, independent of whether or not Boost supports threads.
`ASIO_NO_WIN32_LEAN_AND_MEAN`	By default, 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 `ASIO_NO_WIN32_LEAN_AND_MEAN` prevents `WIN32_LEAN_AND_MEAN` from being defined.
`ASIO_NO_NOMINMAX`	By default, Asio will automatically define `NOMINMAX` when compiling for Windows, to suppress the definition of the `min()` and `max()` macros. The presence of `ASIO_NO_NOMINMAX` prevents `NOMINMAX` from being defined.
`ASIO_NO_DEFAULT_LINKED_LIBS`	When compiling for Windows using Microsoft Visual C++ or Borland C++, 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 `ASIO_NO_DEFAULT_LINKED_LIBS` macro prevents these libraries from being linked.
`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 ASIO_DISABLE_IOCP. * Use the socket object's close() function to simultaneously cancel the outstanding operations and close the socket.
`ASIO_NO_TYPEID`	Disables uses of the `typeid` operator in asio. Defined automatically if `BOOST_NO_TYPEID` is defined.
`ASIO_HASH_MAP_BUCKETS`	Determines the number of buckets in asio's internal `hash_map` objects. The value should be a comma separated list of prime numbers, in ascending order. The `hash_map` implementation will automatically increase the number of buckets as the number of elements in the map increases. Some examples: * Defining `ASIO_HASH_MAP_BUCKETS` to `1021` means that the `hash_map` objects will always contain 1021 buckets, irrespective of the number of elements in the map. * Defining `ASIO_HASH_MAP_BUCKETS` to `53,389,1543` means that the `hash_map` objects will initially contain 53 buckets. The number of buckets will be increased to 389 and then 1543 as elements are added to the map.
`ASIO_USE_BOOST_DATE_TIME_FOR_SOCKET_IOSTREAM`	Changes `basic_socket_streambuf` and `basic_socket_iostream` to use the old Boost.Date_Time interface, rather than chrono.
`ASIO_SEPARATE_COMPILATION`	Uses separately compiled source code for Asio's implementation. See above for further information.
`ASIO_DYN_LINK`	Uses separately compiled source code for Asio's implementation, with symbols exported for inclusion as part of a shared library. See above for further information.
`ASIO_DISABLE_VISIBILITY`	Disables all symbol visibility pragmas. Note: If symbols are hidden, extra care must be taken to ensure that Asio types are not passed across shared library API boundaries.

Compiler/platform feature detection macros

Asio automatically defines preprocessor macros corresponding to the detected available features on a particular compiler and target platform. These macros are named with the prefix ASIO_HAS_, and are listed in the table below.

Many of these macros also have a corresponding ASIO_DISABLE_ macro that may be used to explicitly disable the feature.

In general, ASIO_HAS_ macros should not be explicitly defined by the user, except when absolutely required as a workaround for the latest version of a compiler or platform. For older compiler/platform combinations where a specific ASIO_HAS_ macro is not automatically defined, testing may have shown that a claimed feature isn't sufficiently conformant to be compatible with Asio's needs.

Macro	Description	Macro to disable feature
`ASIO_HAS_ALIAS_TEMPLATES`	Support alias templates on compilers known to allow it.	`ASIO_DISABLE_ALIAS_TEMPLATES`
`ASIO_HAS_BOOST_ARRAY`	Boost array library.	`ASIO_DISABLE_BOOST_ARRAY`
`ASIO_HAS_BOOST_ASSERT`	Boost assert macro.	`ASIO_DISABLE_BOOST_ASSERT`
`ASIO_HAS_BOOST_BIND`	Boost bind function.	`ASIO_DISABLE_BOOST_BIND`
`ASIO_HAS_BOOST_CHRONO`	Boost support for chrono.	`ASIO_DISABLE_BOOST_CHRONO`
`ASIO_HAS_BOOST_CONFIG`	boostify: non-boost code ends here
`ASIO_HAS_BOOST_DATE_TIME`	Boost support for the DateTime library.	`ASIO_DISABLE_BOOST_DATE_TIME`
`ASIO_HAS_BOOST_LIMITS`	Boost limits header.	`ASIO_DISABLE_BOOST_LIMITS`
`ASIO_HAS_BOOST_REGEX`	Boost regex library.	`ASIO_DISABLE_BOOST_REGEX`
`ASIO_HAS_BOOST_THROW_EXCEPTION`	Boost throw_exception function.	`ASIO_DISABLE_BOOST_THROW_EXCEPTION`
`ASIO_HAS_BOOST_WORKAROUND`	Boost's BOOST_WORKAROUND macro.	`ASIO_DISABLE_BOOST_WORKAROUND`
`ASIO_HAS_CHRONO`	Some form of chrono library is available.
`ASIO_HAS_CLANG_LIBCXX`	Clang / libc++ detection.
`ASIO_HAS_CONCEPTS`	Support concepts on compilers known to allow them.	`ASIO_DISABLE_CONCEPTS`
`ASIO_HAS_CONSTANT_EXPRESSION_SFINAE`	Support SFINAE use of constant expressions on compilers known to allow it.	`ASIO_DISABLE_CONSTANT_EXPRESSION_SFINAE`
`ASIO_HAS_CONSTEXPR`	Support constexpr on compilers known to allow it.	`ASIO_DISABLE_CONSTEXPR`
`ASIO_HAS_CO_AWAIT`	Support the co_await keyword on compilers known to allow it.	`ASIO_DISABLE_CO_AWAIT`
`ASIO_HAS_CSTDINT`	Standard library support for the cstdint header.	`ASIO_DISABLE_CSTDINT`
`ASIO_HAS_CXX11_ALLOCATORS`	Standard library support for the C++11 allocator additions.	`ASIO_DISABLE_CXX11_ALLOCATORS`
`ASIO_HAS_DECLTYPE`	Support automatic type deduction on compilers known to support it.	`ASIO_DISABLE_DECLTYPE`
`ASIO_HAS_DEFAULT_FUNCTION_TEMPLATE_ARGUMENTS`	Support default function template arguments on compilers known to allow it.	`ASIO_DISABLE_DEFAULT_FUNCTION_TEMPLATE_ARGUMENTS`
`ASIO_HAS_DEV_POLL`	Solaris: /dev/poll.	`ASIO_DISABLE_DEV_POLL`
`ASIO_HAS_EPOLL`	Linux: epoll, eventfd and timerfd.	`ASIO_DISABLE_EPOLL`
`ASIO_HAS_EVENTFD`	Linux: epoll, eventfd and timerfd.	`ASIO_DISABLE_EVENTFD`
`ASIO_HAS_GETADDRINFO`	Can use getaddrinfo() and getnameinfo().	`ASIO_DISABLE_GETADDRINFO`
`ASIO_HAS_HANDLER_HOOKS`	Handler hooking. Disabled for ancient Borland C++ and gcc compilers.	`ASIO_DISABLE_HANDLER_HOOKS`
`ASIO_HAS_IOCP`	Windows: IO Completion Ports.	`ASIO_DISABLE_IOCP`
`ASIO_HAS_KQUEUE`	Mac OS X, FreeBSD, NetBSD, OpenBSD: kqueue.	`ASIO_DISABLE_KQUEUE`
`ASIO_HAS_LOCAL_SOCKETS`	UNIX domain sockets.	`ASIO_DISABLE_LOCAL_SOCKETS`
`ASIO_HAS_MOVE`	Support move construction and assignment on compilers known to allow it.	`ASIO_DISABLE_MOVE`
`ASIO_HAS_MSG_NOSIGNAL`	Kernel support for MSG_NOSIGNAL.
`ASIO_HAS_NOEXCEPT`	Support noexcept on compilers known to allow it.	`ASIO_DISABLE_NOEXCEPT`
`ASIO_HAS_NULLPTR`	Standard library support for the nullptr_t type.	`ASIO_DISABLE_NULLPTR`
`ASIO_HAS_POSIX_STREAM_DESCRIPTOR`	POSIX: stream-oriented file descriptors.	`ASIO_DISABLE_POSIX_STREAM_DESCRIPTOR`
`ASIO_HAS_PTHREADS`	POSIX threads.
`ASIO_HAS_REF_QUALIFIED_FUNCTIONS`	Support ref-qualified functions on compilers known to allow it.	`ASIO_DISABLE_REF_QUALIFIED_FUNCTIONS`
`ASIO_HAS_RETURN_TYPE_DEDUCTION`	Support return type deduction on compilers known to allow it.	`ASIO_DISABLE_RETURN_TYPE_DEDUCTION`
`ASIO_HAS_SECURE_RTL`	Microsoft Visual C++'s secure C runtime library.	`ASIO_DISABLE_SECURE_RTL`
`ASIO_HAS_SERIAL_PORT`	Serial ports.	`ASIO_DISABLE_SERIAL_PORT`
`ASIO_HAS_SFINAE_VARIABLE_TEMPLATES`	Support SFINAEd template variables on compilers known to allow it.	`ASIO_DISABLE_SFINAE_VARIABLE_TEMPLATES`
`ASIO_HAS_SIGACTION`	Can use sigaction() instead of signal().	`ASIO_DISABLE_SIGACTION`
`ASIO_HAS_SIGNAL`	Can use signal().	`ASIO_DISABLE_SIGNAL`
`ASIO_HAS_SOURCE_LOCATION`	Standard library has a source_location that we can use.	`ASIO_DISABLE_SOURCE_LOCATION`
`ASIO_HAS_SSIZE_T`	Support for POSIX ssize_t typedef.	`ASIO_DISABLE_SSIZE_T`
`ASIO_HAS_STD_ADDRESSOF`	Standard library support for addressof.	`ASIO_DISABLE_STD_ADDRESSOF`
`ASIO_HAS_STD_ALLOCATOR_ARG`	Standard library support for allocator_arg_t.	`ASIO_DISABLE_STD_ALLOCATOR_ARG`
`ASIO_HAS_STD_ANY`	Standard library support for std::any.	`ASIO_DISABLE_STD_ANY`
`ASIO_HAS_STD_ARRAY`	Standard library support for arrays.	`ASIO_DISABLE_STD_ARRAY`
`ASIO_HAS_STD_ATOMIC`	Standard library support for atomic operations.	`ASIO_DISABLE_STD_ATOMIC`
`ASIO_HAS_STD_CALL_ONCE`	Standard library support for the call_once function.	`ASIO_DISABLE_STD_CALL_ONCE`
`ASIO_HAS_STD_CHRONO`	Standard library support for chrono. Some standard libraries (such as the libstdc++ shipped with gcc 4.6) provide monotonic_clock as per early C++0x drafts, rather than the eventually standardised name of steady_clock.	`ASIO_DISABLE_STD_CHRONO`
`ASIO_HAS_STD_CHRONO_MONOTONIC_CLOCK`	Standard library support for chrono. Some standard libraries (such as the libstdc++ shipped with gcc 4.6) provide monotonic_clock as per early C++0x drafts, rather than the eventually standardised name of steady_clock.
`ASIO_HAS_STD_COROUTINE`	Standard library support for coroutines.	`ASIO_DISABLE_STD_COROUTINE`
`ASIO_HAS_STD_EXCEPTION_PTR`	Standard library support for std::exception_ptr and std::current_exception.	`ASIO_DISABLE_STD_EXCEPTION_PTR`
`ASIO_HAS_STD_EXPERIMENTAL_SOURCE_LOCATION`	Standard library support for std::experimental::source_location.	`ASIO_DISABLE_STD_EXPERIMENTAL_SOURCE_LOCATION`
`ASIO_HAS_STD_EXPERIMENTAL_STRING_VIEW`	Standard library support for std::experimental::string_view.	`ASIO_DISABLE_STD_EXPERIMENTAL_STRING_VIEW`
`ASIO_HAS_STD_FUNCTION`	Standard library support for the function class.	`ASIO_DISABLE_STD_FUNCTION`
`ASIO_HAS_STD_FUTURE`	Standard library support for futures.	`ASIO_DISABLE_STD_FUTURE`
`ASIO_HAS_STD_INVOKE_RESULT`	Standard library has invoke_result (which supersedes result_of).	`ASIO_DISABLE_STD_INVOKE_RESULT`
`ASIO_HAS_STD_IOSTREAM_MOVE`	Standard library support for iostream move construction and assignment.	`ASIO_DISABLE_STD_IOSTREAM_MOVE`
`ASIO_HAS_STD_MUTEX_AND_CONDVAR`	Standard library support for the mutex and condition variable classes.	`ASIO_DISABLE_STD_MUTEX_AND_CONDVAR`
`ASIO_HAS_STD_NESTED_EXCEPTION`	Standard library support for std::nested_exception.	`ASIO_DISABLE_STD_NESTED_EXCEPTION`
`ASIO_HAS_STD_SHARED_PTR`	Standard library support for shared_ptr and weak_ptr.	`ASIO_DISABLE_STD_SHARED_PTR`
`ASIO_HAS_STD_STRING_VIEW`	Standard library support for std::string_view.	`ASIO_DISABLE_STD_STRING_VIEW`
`ASIO_HAS_STD_SYSTEM_ERROR`	Standard library support for system errors.	`ASIO_DISABLE_STD_SYSTEM_ERROR`
`ASIO_HAS_STD_THREAD`	Standard library support for the thread class.	`ASIO_DISABLE_STD_THREAD`
`ASIO_HAS_STD_TYPE_TRAITS`	Standard library support for type traits.	`ASIO_DISABLE_STD_TYPE_TRAITS`
`ASIO_HAS_STRING_VIEW`	Standard library has a string_view that we can use.	`ASIO_DISABLE_STRING_VIEW`
`ASIO_HAS_THREADS`	Threads.	`ASIO_DISABLE_THREADS`
`ASIO_HAS_THREAD_KEYWORD_EXTENSION`	Support for the __thread keyword extension.	`ASIO_DISABLE_THREAD_KEYWORD_EXTENSION`
`ASIO_HAS_TIMERFD`	Linux: epoll, eventfd and timerfd.
`ASIO_HAS_UNISTD_H`	On POSIX (and POSIX-like) platforms we need to include unistd.h in order to get access to the various platform feature macros, e.g. to be able to test for threads support.
`ASIO_HAS_VARIABLE_TEMPLATES`	Support template variables on compilers known to allow it.	`ASIO_DISABLE_VARIABLE_TEMPLATES`
`ASIO_HAS_VARIADIC_TEMPLATES`	Support variadic templates on compilers known to allow it.	`ASIO_DISABLE_VARIADIC_TEMPLATES`
`ASIO_HAS_WINDOWS_OBJECT_HANDLE`	Windows: object handles.	`ASIO_DISABLE_WINDOWS_OBJECT_HANDLE`
`ASIO_HAS_WINDOWS_OVERLAPPED_PTR`	Windows: OVERLAPPED wrapper.	`ASIO_DISABLE_WINDOWS_OVERLAPPED_PTR`
`ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE`	Windows: random access handles.	`ASIO_DISABLE_WINDOWS_RANDOM_ACCESS_HANDLE`
`ASIO_HAS_WINDOWS_STREAM_HANDLE`	Windows: stream handles.	`ASIO_DISABLE_WINDOWS_STREAM_HANDLE`
`ASIO_HAS_WORKING_EXPRESSION_SFINAE`	Enable workarounds for lack of working expression SFINAE.	`ASIO_DISABLE_WORKING_EXPRESSION_SFINAE`

Mailing List

A mailing list specifically for Asio may be found on SourceForge.net. Newsgroup access is provided via Gmane.

Wiki

Users are encouraged to share examples, tips and FAQs on the Asio wiki, which is located at http://think-async.com/Asio/.