1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Using Boost.Asio</title> 5<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../boost_asio.html" title="Boost.Asio"> 8<link rel="up" href="../boost_asio.html" title="Boost.Asio"> 9<link rel="prev" href="overview/implementation.html" title="Platform-Specific Implementation Notes"> 10<link rel="next" href="tutorial.html" title="Tutorial"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 15<td align="center"><a href="../../../index.html">Home</a></td> 16<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="overview/implementation.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_asio.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../boost_asio.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_asio.using"></a><a class="link" href="using.html" title="Using Boost.Asio">Using Boost.Asio</a> 28</h2></div></div></div> 29<h4> 30<a name="boost_asio.using.h0"></a> 31 <span class="phrase"><a name="boost_asio.using.supported_platforms"></a></span><a class="link" href="using.html#boost_asio.using.supported_platforms">Supported 32 Platforms</a> 33 </h4> 34<p> 35 The following platform and compiler combinations are regularly tested: 36 </p> 37<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 38<li class="listitem"> 39 Linux using g++ 4.1 or later 40 </li> 41<li class="listitem"> 42 Linux using clang 3.2 or later 43 </li> 44<li class="listitem"> 45 FreeBSD using g++ 4.1 or later 46 </li> 47<li class="listitem"> 48 macOS using Xcode 8 or later 49 </li> 50<li class="listitem"> 51 Win32 using Visual C++ 9.0 or later 52 </li> 53<li class="listitem"> 54 Win32 using g++ 4.1 or later (MinGW) 55 </li> 56<li class="listitem"> 57 Win64 using Visual C++ 9.0 or later 58 </li> 59</ul></div> 60<p> 61 The following platforms may also work: 62 </p> 63<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 64<li class="listitem"> 65 AIX 66 </li> 67<li class="listitem"> 68 Android 69 </li> 70<li class="listitem"> 71 HP-UX 72 </li> 73<li class="listitem"> 74 iOS 75 </li> 76<li class="listitem"> 77 NetBSD 78 </li> 79<li class="listitem"> 80 OpenBSD 81 </li> 82<li class="listitem"> 83 QNX Neutrino 84 </li> 85<li class="listitem"> 86 Solaris 87 </li> 88<li class="listitem"> 89 Tru64 90 </li> 91<li class="listitem"> 92 Win32 using Cygwin. (<code class="computeroutput">__USE_W32_SOCKETS</code> must be defined.) 93 </li> 94</ul></div> 95<h4> 96<a name="boost_asio.using.h1"></a> 97 <span class="phrase"><a name="boost_asio.using.dependencies"></a></span><a class="link" href="using.html#boost_asio.using.dependencies">Dependencies</a> 98 </h4> 99<p> 100 The following libraries must be available in order to link programs that use 101 Boost.Asio: 102 </p> 103<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 104<li class="listitem"> 105 Boost.System for the <code class="computeroutput">boost::system::error_code</code> and <code class="computeroutput">boost::system::system_error</code> 106 classes. 107 </li> 108<li class="listitem"> 109 Boost.Coroutine (optional) if you use <a class="link" href="reference/spawn.html" title="spawn"><code class="computeroutput">spawn()</code></a> 110 to launch coroutines. 111 </li> 112<li class="listitem"> 113 Boost.Regex (optional) if you use any of the <a class="link" href="reference/read_until.html" title="read_until"><code class="computeroutput">read_until()</code></a> 114 or <a class="link" href="reference/async_read_until.html" title="async_read_until"><code class="computeroutput">async_read_until()</code></a> 115 overloads that take a <code class="computeroutput">boost::regex</code> parameter. 116 </li> 117<li class="listitem"> 118 <a href="http://www.openssl.org" target="_top">OpenSSL</a> (optional) if you use 119 Boost.Asio's SSL support. 120 </li> 121</ul></div> 122<p> 123 Furthermore, some of the examples also require the Boost.Thread, Boost.Date_Time 124 or Boost.Serialization libraries. 125 </p> 126<div class="note"><table border="0" summary="Note"> 127<tr> 128<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> 129<th align="left">Note</th> 130</tr> 131<tr><td align="left" valign="top"><p> 132 With MSVC or Borland C++ you may want to add <code class="computeroutput">-DBOOST_DATE_TIME_NO_LIB</code> 133 and <code class="computeroutput">-DBOOST_REGEX_NO_LIB</code> to your project settings to disable 134 autolinking of the Boost.Date_Time and Boost.Regex libraries respectively. 135 Alternatively, you may choose to build these libraries and link to them. 136 </p></td></tr> 137</table></div> 138<h4> 139<a name="boost_asio.using.h2"></a> 140 <span class="phrase"><a name="boost_asio.using.building_boost_libraries"></a></span><a class="link" href="using.html#boost_asio.using.building_boost_libraries">Building 141 Boost Libraries</a> 142 </h4> 143<p> 144 You may build the subset of Boost libraries required to use Boost.Asio and 145 its examples by running the following command from the root of the Boost download 146 package: 147 </p> 148<pre class="programlisting">b2 --with-system --with-thread --with-date_time --with-regex --with-serialization stage 149</pre> 150<p> 151 This assumes that you have already built <code class="computeroutput">b2</code>. Consult the Boost.Build 152 documentation for more details. 153 </p> 154<h4> 155<a name="boost_asio.using.h3"></a> 156 <span class="phrase"><a name="boost_asio.using.optional_separate_compilation"></a></span><a class="link" href="using.html#boost_asio.using.optional_separate_compilation">Optional 157 separate compilation</a> 158 </h4> 159<p> 160 By default, Boost.Asio is a header-only library. However, some developers may 161 prefer to build Boost.Asio using separately compiled source code. To do this, 162 add <code class="computeroutput">#include <boost/asio/impl/src.hpp></code> to one (and only 163 one) source file in a program, then build the program with <code class="computeroutput">BOOST_ASIO_SEPARATE_COMPILATION</code> 164 defined in the project/compiler settings. Alternatively, <code class="computeroutput">BOOST_ASIO_DYN_LINK</code> 165 may be defined to build a separately-compiled Boost.Asio as part of a shared 166 library. 167 </p> 168<p> 169 If using Boost.Asio's SSL support, you will also need to add <code class="computeroutput">#include 170 <boost/asio/ssl/impl/src.hpp></code>. 171 </p> 172<h4> 173<a name="boost_asio.using.h4"></a> 174 <span class="phrase"><a name="boost_asio.using.macros"></a></span><a class="link" href="using.html#boost_asio.using.macros">Macros</a> 175 </h4> 176<p> 177 The macros listed in the table below may be used to control the behaviour of 178 Boost.Asio. 179 </p> 180<div class="informaltable"><table class="table"> 181<colgroup> 182<col> 183<col> 184</colgroup> 185<thead><tr> 186<th> 187 <p> 188 Macro 189 </p> 190 </th> 191<th> 192 <p> 193 Description 194 </p> 195 </th> 196</tr></thead> 197<tbody> 198<tr> 199<td> 200 <p> 201 <code class="computeroutput">BOOST_ASIO_ENABLE_BUFFER_DEBUGGING</code> 202 </p> 203 </td> 204<td> 205 <p> 206 Enables Boost.Asio's buffer debugging support, which can help identify 207 when invalid buffers are used in read or write operations (e.g. if 208 a std::string object being written is destroyed before the write 209 operation completes). 210 </p> 211 <p> 212 When using Microsoft Visual C++ 11.0 or later, this macro is defined 213 automatically if the compiler's iterator debugging support is enabled, 214 unless <code class="computeroutput">BOOST_ASIO_DISABLE_BUFFER_DEBUGGING</code> has been 215 defined. 216 </p> 217 <p> 218 When using g++, this macro is defined automatically if standard library 219 debugging is enabled (<code class="computeroutput">_GLIBCXX_DEBUG</code> is defined), unless 220 <code class="computeroutput">BOOST_ASIO_DISABLE_BUFFER_DEBUGGING</code> has been defined. 221 </p> 222 </td> 223</tr> 224<tr> 225<td> 226 <p> 227 <code class="computeroutput">BOOST_ASIO_DISABLE_BUFFER_DEBUGGING</code> 228 </p> 229 </td> 230<td> 231 <p> 232 Explictly disables Boost.Asio's buffer debugging support. 233 </p> 234 </td> 235</tr> 236<tr> 237<td> 238 <p> 239 <code class="computeroutput">BOOST_ASIO_DISABLE_DEV_POLL</code> 240 </p> 241 </td> 242<td> 243 <p> 244 Explicitly disables <code class="literal">/dev/poll</code> support on Solaris, 245 forcing the use of a <code class="computeroutput">select</code>-based implementation. 246 </p> 247 </td> 248</tr> 249<tr> 250<td> 251 <p> 252 <code class="computeroutput">BOOST_ASIO_DISABLE_EPOLL</code> 253 </p> 254 </td> 255<td> 256 <p> 257 Explicitly disables <code class="computeroutput">epoll</code> support on Linux, forcing 258 the use of a <code class="computeroutput">select</code>-based implementation. 259 </p> 260 </td> 261</tr> 262<tr> 263<td> 264 <p> 265 <code class="computeroutput">BOOST_ASIO_DISABLE_EVENTFD</code> 266 </p> 267 </td> 268<td> 269 <p> 270 Explicitly disables <code class="computeroutput">eventfd</code> support on Linux, forcing 271 the use of a pipe to interrupt blocked epoll/select system calls. 272 </p> 273 </td> 274</tr> 275<tr> 276<td> 277 <p> 278 <code class="computeroutput">BOOST_ASIO_DISABLE_KQUEUE</code> 279 </p> 280 </td> 281<td> 282 <p> 283 Explicitly disables <code class="computeroutput">kqueue</code> support on macOS and BSD 284 variants, forcing the use of a <code class="computeroutput">select</code>-based implementation. 285 </p> 286 </td> 287</tr> 288<tr> 289<td> 290 <p> 291 <code class="computeroutput">BOOST_ASIO_DISABLE_IOCP</code> 292 </p> 293 </td> 294<td> 295 <p> 296 Explicitly disables I/O completion ports support on Windows, forcing 297 the use of a <code class="computeroutput">select</code>-based implementation. 298 </p> 299 </td> 300</tr> 301<tr> 302<td> 303 <p> 304 <code class="computeroutput">BOOST_ASIO_DISABLE_THREADS</code> 305 </p> 306 </td> 307<td> 308 <p> 309 Explicitly disables Boost.Asio's threading support, independent of 310 whether or not Boost as a whole supports threads. 311 </p> 312 </td> 313</tr> 314<tr> 315<td> 316 <p> 317 <code class="computeroutput">BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN</code> 318 </p> 319 </td> 320<td> 321 <p> 322 By default, Boost.Asio will automatically define <code class="computeroutput">WIN32_LEAN_AND_MEAN</code> 323 when compiling for Windows, to minimise the number of Windows SDK 324 header files and features that are included. The presence of <code class="computeroutput">BOOST_ASIO_NO_WIN32_LEAN_AND_MEAN</code> 325 prevents <code class="computeroutput">WIN32_LEAN_AND_MEAN</code> from being defined. 326 </p> 327 </td> 328</tr> 329<tr> 330<td> 331 <p> 332 <code class="computeroutput">BOOST_ASIO_NO_NOMINMAX</code> 333 </p> 334 </td> 335<td> 336 <p> 337 By default, Boost.Asio will automatically define <code class="computeroutput">NOMINMAX</code> 338 when compiling for Windows, to suppress the definition of the <code class="computeroutput">min()</code> 339 and <code class="computeroutput">max()</code> macros. The presence of <code class="computeroutput">BOOST_ASIO_NO_NOMINMAX</code> 340 prevents <code class="computeroutput">NOMINMAX</code> from being defined. 341 </p> 342 </td> 343</tr> 344<tr> 345<td> 346 <p> 347 <code class="computeroutput">BOOST_ASIO_NO_DEFAULT_LINKED_LIBS</code> 348 </p> 349 </td> 350<td> 351 <p> 352 When compiling for Windows using Microsoft Visual C++ or Borland 353 C++, Boost.Asio will automatically link in the necessary Windows 354 SDK libraries for sockets support (i.e. <code class="literal">ws2_32.lib</code> 355 and <code class="literal">mswsock.lib</code>, or <code class="literal">ws2.lib</code> 356 when building for Windows CE). The <code class="computeroutput">BOOST_ASIO_NO_DEFAULT_LINKED_LIBS</code> 357 macro prevents these libraries from being linked. 358 </p> 359 </td> 360</tr> 361<tr> 362<td> 363 <p> 364 <code class="computeroutput">BOOST_ASIO_ENABLE_CANCELIO</code> 365 </p> 366 </td> 367<td> 368 <p> 369 Enables use of the <code class="computeroutput">CancelIo</code> function on older versions 370 of Windows. If not enabled, calls to <code class="computeroutput">cancel()</code> on a socket 371 object will always fail with <code class="computeroutput">asio::error::operation_not_supported</code> 372 when run on Windows XP, Windows Server 2003, and earlier versions 373 of Windows. When running on Windows Vista, Windows Server 2008, and 374 later, the <code class="computeroutput">CancelIoEx</code> function is always used. 375 </p> 376 <p> 377 The <code class="computeroutput">CancelIo</code> function has two issues that should be 378 considered before enabling its use: 379 </p> 380 <p> 381 * It will only cancel asynchronous operations that were initiated 382 in the current thread. 383 </p> 384 <p> 385 * It can appear to complete without error, but the request to cancel 386 the unfinished operations may be silently ignored by the operating 387 system. Whether it works or not seems to depend on the drivers that 388 are installed. 389 </p> 390 <p> 391 For portable cancellation, consider using one of the following alternatives: 392 </p> 393 <p> 394 * Disable asio's I/O completion port backend by defining BOOST_ASIO_DISABLE_IOCP. 395 </p> 396 <p> 397 * Use the socket object's close() function to simultaneously cancel 398 the outstanding operations and close the socket. 399 </p> 400 </td> 401</tr> 402<tr> 403<td> 404 <p> 405 <code class="computeroutput">BOOST_ASIO_NO_TYPEID</code> 406 </p> 407 </td> 408<td> 409 <p> 410 Disables uses of the <code class="computeroutput">typeid</code> operator in Boost.Asio. 411 Defined automatically if <code class="computeroutput">BOOST_NO_TYPEID</code> is defined. 412 </p> 413 </td> 414</tr> 415<tr> 416<td> 417 <p> 418 <code class="computeroutput">BOOST_ASIO_HASH_MAP_BUCKETS</code> 419 </p> 420 </td> 421<td> 422 <p> 423 Determines the number of buckets in Boost.Asio's internal <code class="computeroutput">hash_map</code> 424 objects. The value should be a comma separated list of prime numbers, 425 in ascending order. The <code class="computeroutput">hash_map</code> implementation will 426 automatically increase the number of buckets as the number of elements 427 in the map increases. 428 </p> 429 <p> 430 Some examples: 431 </p> 432 <p> 433 * Defining <code class="computeroutput">BOOST_ASIO_HASH_MAP_BUCKETS</code> to <code class="computeroutput">1021</code> 434 means that the <code class="computeroutput">hash_map</code> objects will always contain 435 1021 buckets, irrespective of the number of elements in the map. 436 </p> 437 <p> 438 * Defining <code class="computeroutput">BOOST_ASIO_HASH_MAP_BUCKETS</code> to <code class="computeroutput">53,389,1543</code> 439 means that the <code class="computeroutput">hash_map</code> objects will initially contain 440 53 buckets. The number of buckets will be increased to 389 and then 441 1543 as elements are added to the map. 442 </p> 443 </td> 444</tr> 445</tbody> 446</table></div> 447<h4> 448<a name="boost_asio.using.h5"></a> 449 <span class="phrase"><a name="boost_asio.using.mailing_list"></a></span><a class="link" href="using.html#boost_asio.using.mailing_list">Mailing 450 List</a> 451 </h4> 452<p> 453 A mailing list specifically for Boost.Asio may be found on <a href="http://sourceforge.net/mail/?group_id=122478" target="_top">SourceForge.net</a>. 454 Newsgroup access is provided via <a href="http://dir.gmane.org/gmane.comp.lib.boost.asio.user" target="_top">Gmane</a>. 455 </p> 456<h4> 457<a name="boost_asio.using.h6"></a> 458 <span class="phrase"><a name="boost_asio.using.wiki"></a></span><a class="link" href="using.html#boost_asio.using.wiki">Wiki</a> 459 </h4> 460<p> 461 Users are encouraged to share examples, tips and FAQs on the Boost.Asio wiki, 462 which is located at <a href="http://think-async.com/Asio/" target="_top">http://think-async.com/Asio/</a>. 463 </p> 464</div> 465<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 466<td align="left"></td> 467<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 468 Kohlhoff<p> 469 Distributed under the Boost Software License, Version 1.0. (See accompanying 470 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 471 </p> 472</div></td> 473</tr></table> 474<hr> 475<div class="spirit-nav"> 476<a accesskey="p" href="overview/implementation.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_asio.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../boost_asio.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 477</div> 478</body> 479</html> 480
