1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Streams, Short Reads and Short Writes</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="../core.html" title="Core Concepts and Functionality"> 9<link rel="prev" href="buffers.html" title="Buffers"> 10<link rel="next" href="reactor.html" title="Reactor-Style Operations"> 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="buffers.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.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="reactor.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h4 class="title"> 27<a name="boost_asio.overview.core.streams"></a><a class="link" href="streams.html" title="Streams, Short Reads and Short Writes">Streams, Short Reads 28 and Short Writes</a> 29</h4></div></div></div> 30<p> 31 Many I/O objects in Boost.Asio are stream-oriented. This means that: 32 </p> 33<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 34<li class="listitem"> 35 There are no message boundaries. The data being transferred is a continuous 36 sequence of bytes. 37 </li> 38<li class="listitem"> 39 Read or write operations may transfer fewer bytes than requested. This 40 is referred to as a short read or short write. 41 </li> 42</ul></div> 43<p> 44 Objects that provide stream-oriented I/O model one or more of the following 45 type requirements: 46 </p> 47<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 48<li class="listitem"> 49 <code class="computeroutput"><span class="identifier">SyncReadStream</span></code>, where 50 synchronous read operations are performed using a member function called 51 <code class="computeroutput"><span class="identifier">read_some</span><span class="special">()</span></code>. 52 </li> 53<li class="listitem"> 54 <code class="computeroutput"><span class="identifier">AsyncReadStream</span></code>, where 55 asynchronous read operations are performed using a member function 56 called <code class="computeroutput"><span class="identifier">async_read_some</span><span class="special">()</span></code>. 57 </li> 58<li class="listitem"> 59 <code class="computeroutput"><span class="identifier">SyncWriteStream</span></code>, where 60 synchronous write operations are performed using a member function 61 called <code class="computeroutput"><span class="identifier">write_some</span><span class="special">()</span></code>. 62 </li> 63<li class="listitem"> 64 <code class="computeroutput"><span class="identifier">AsyncWriteStream</span></code>, where 65 asynchronous write operations are performed using a member function 66 called <code class="computeroutput"><span class="identifier">async_write_some</span><span class="special">()</span></code>. 67 </li> 68</ul></div> 69<p> 70 Examples of stream-oriented I/O objects include <code class="computeroutput"><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span></code>, 71 <code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span><span class="special"><></span></code>, 72 <code class="computeroutput"><span class="identifier">posix</span><span class="special">::</span><span class="identifier">stream_descriptor</span></code>, <code class="computeroutput"><span class="identifier">windows</span><span class="special">::</span><span class="identifier">stream_handle</span></code>, 73 etc. 74 </p> 75<p> 76 Programs typically want to transfer an exact number of bytes. When a short 77 read or short write occurs the program must restart the operation, and 78 continue to do so until the required number of bytes has been transferred. 79 Boost.Asio provides generic functions that do this automatically: <code class="computeroutput"><span class="identifier">read</span><span class="special">()</span></code>, 80 <code class="computeroutput"><span class="identifier">async_read</span><span class="special">()</span></code>, 81 <code class="computeroutput"><span class="identifier">write</span><span class="special">()</span></code> 82 and <code class="computeroutput"><span class="identifier">async_write</span><span class="special">()</span></code>. 83 </p> 84<h6> 85<a name="boost_asio.overview.core.streams.h0"></a> 86 <span class="phrase"><a name="boost_asio.overview.core.streams.why_eof_is_an_error"></a></span><a class="link" href="streams.html#boost_asio.overview.core.streams.why_eof_is_an_error">Why EOF 87 is an Error</a> 88 </h6> 89<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 90<li class="listitem"> 91 The end of a stream can cause <code class="computeroutput"><span class="identifier">read</span></code>, 92 <code class="computeroutput"><span class="identifier">async_read</span></code>, <code class="computeroutput"><span class="identifier">read_until</span></code> or <code class="computeroutput"><span class="identifier">async_read_until</span></code> 93 functions to violate their contract. E.g. a read of N bytes may finish 94 early due to EOF. 95 </li> 96<li class="listitem"> 97 An EOF error may be used to distinguish the end of a stream from a 98 successful read of size 0. 99 </li> 100</ul></div> 101<h6> 102<a name="boost_asio.overview.core.streams.h1"></a> 103 <span class="phrase"><a name="boost_asio.overview.core.streams.see_also"></a></span><a class="link" href="streams.html#boost_asio.overview.core.streams.see_also">See 104 Also</a> 105 </h6> 106<p> 107 <a class="link" href="../../reference/async_read.html" title="async_read">async_read()</a>, <a class="link" href="../../reference/async_write.html" title="async_write">async_write()</a>, <a class="link" href="../../reference/read.html" title="read">read()</a>, <a class="link" href="../../reference/write.html" title="write">write()</a>, 108 <a class="link" href="../../reference/AsyncReadStream.html" title="Buffer-oriented asynchronous read stream requirements">AsyncReadStream</a>, 109 <a class="link" href="../../reference/AsyncWriteStream.html" title="Buffer-oriented asynchronous write stream requirements">AsyncWriteStream</a>, 110 <a class="link" href="../../reference/SyncReadStream.html" title="Buffer-oriented synchronous read stream requirements">SyncReadStream</a>, 111 <a class="link" href="../../reference/SyncWriteStream.html" title="Buffer-oriented synchronous write stream requirements">SyncWriteStream</a>. 112 </p> 113</div> 114<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 115<td align="left"></td> 116<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 117 Kohlhoff<p> 118 Distributed under the Boost Software License, Version 1.0. (See accompanying 119 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>) 120 </p> 121</div></td> 122</tr></table> 123<hr> 124<div class="spirit-nav"> 125<a accesskey="p" href="buffers.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.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="reactor.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 126</div> 127</body> 128</html> 129
