📄 c-netapi3.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><link rel="STYLESHEET" type="text/css" href="wrs.css"><title> Networking APIs </title></head><body bgcolor="FFFFFF"><p class="navbar" align="right"><a href="index.html"><img border="0" alt="[Contents]" src="icons/contents.gif"></a><a href="c-netapi.html"><img border="0" alt="[Index]" src="icons/index.gif"></a><a href="c-netapi.html"><img border="0" alt="[Top]" src="icons/top.gif"></a><a href="c-netapi2.html"><img border="0" alt="[Prev]" src="icons/prev.gif"></a><a href="c-dns.html"><img border="0" alt="[Next]" src="icons/next.gif"></a></p><font face="Helvetica, sans-serif" class="sans"><h3 class="H2"><i><a name="89411">7.3 Zbuf Sockets</a></i></h3></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89413"> </a>VxWorks includes an alternative set of socket calls based on a data abstraction called a <i class="term">zbuf</i>, which permits you to share data buffers (or portions of data buffers) between separate software modules. The <i class="term">zbuf socket interface</i> allows applications to read and write UNIX BSD sockets without copying data between application buffers and network buffers. You can use zbufs with either UDP or TCP applications. The TCP subset of this new interface is sometimes called <i class="term">zero-copy TCP</i>. </p><dd><p class="Body"><a name="89415"> </a>Zbuf-based socket calls are <i class="term">interoperable</i> with the standard BSD socket interface: the other end of a socket has no way of telling whether your end is using zbuf-based calls or traditional calls. </p><dd><p class="Body"><a name="89416"> </a>However, zbuf-based socket calls are<i class="term"> </i><i class="emphasis">not source-compatible</i> with the standard BSD socket interface: you must call different socket functions to use the zbuf interface. Applications that use the zbuf interface are thus less portable.</p></dl></dl><dl class="margin"><dd><p class="table" callout><table border="0" cellpadding="0" cellspacing="0"><tr valign="top"><td valign="top" width="40"><br><img border="0" alt="*" src="icons/warning.gif"></td><td><hr><div class="CalloutCell"><a name="92756"><b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">WARNING: </font></b></a>The send socket buffer size (set during configuration, using the macros <b class="symbol_UC">TCP_SND_SIZE_DFLT</b> or <b class="symbol_UC">UDP_SND_SIZE_DFLT</b>) must exceed that of any zbufs sent over the socket</div></td></tr><tr valign="top"><td></td><td><hr></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p callout><dl class="margin"><dd><p class="Body"><a name="89428"> </a>To link (and initialize) the zbuf socket interface, reconfigure VxWorks. The relevant configuration macro is <b class="symbol_UC">INCLUDE_ZBUF_SOCK</b>.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="89430">7.3.1 Zbuf Calls to Send Existing Data Buffers</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="94464"> </a>The simplest way to use zbuf sockets is to call either <b class="routine"><i class="routine">zbufSockBufSend</i></b><b>( )</b> (in place of <b class="routine"><i class="routine">send</i></b><b>( )</b> for a TCP connection) or <b class="routine"><i class="routine">zbufSockBufSendto</i></b><b>( )</b> (in place of <b class="routine"><i class="routine">sendto</i></b><b>( )</b> for a UDP datagram). In either case, you supply a pointer to your application's data buffer containing the data or message to send, and the network protocol uses that same buffer rather than copying the data out of it.</p></dl></dl><dl class="margin"><dd><p class="table" callout><table border="0" cellpadding="0" cellspacing="0"><tr valign="top"><td valign="top" width="40"><br><img border="0" alt="*" src="icons/warning.gif"></td><td><hr><div class="CalloutCell"><a name="92735"><b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">WARNING: </font></b></a>Using zbufs allows different modules to share the same buffers. This lets your application avoid the performance hit associated with copying the buffer. To make this work, your application must not modify (let alone free!) the data buffer while network software is still using it. Instead of freeing your buffer explicitly, you can supply a free-routine callback: a pointer to a routine that knows how to free the buffer. The zbuf library keeps track of how many zbufs point to a data buffer, and calls the free routine when the data buffer is no longer in use.</div></td></tr><tr valign="top"><td></td><td><hr></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p callout><dl class="margin"><dd><p class="Body"><a name="89448"> </a>To receive socket data using zbufs, see the following sections. <a href="c-netapi3.html#89455"><i class="title">7.3.2 Manipulating the Zbuf Data Structure</i></a> describes the routines to create and manage zbufs, and <a href="c-netapi3.html#89759"><i class="title">7.3.3 Zbuf Socket Calls</i></a> introduces the remaining zbuf-specific socket routines. See also the reference entries for <b class="library">zbufLib</b> and <b class="library">zbufSockLib</b>.</p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H3"><i><a name="89455">7.3.2 Manipulating the Zbuf Data Structure</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89457"> </a>A zbuf has three essential properties:</p></dl><dl class="margin"><p class="listspace"><ul class="Bullet" type="disc"><li><a name="89458"> </a>A zbuf holds a sequence of bytes.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="89459"> </a>The data in a zbuf is organized into one or more <i class="term">segments</i> of contiguous data. Successive zbuf segments are not usually contiguous to each other.</li></ul></p><p class="listspace"><ul class="Bullet" type="disc"><li><a name="89460"> </a>Zbuf segments refer to data buffers through pointers. The underlying data buffers can be shared by more than one zbuf segment.</li></ul></p></dl><dl class="margin"><dd><p class="Body"><a name="89461"> </a>Zbuf segments are at the heart of how zbufs minimize data copying: if you have a data buffer, you can incorporate it (by reference, so that only pointers and lengths move around) into a new zbuf segment. Conversely, you can get pointers to the data in zbuf segments, and examine the data there directly. </p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="89462">Zbuf Byte Locations</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89464"> </a>You can address the contents of a zbuf by <i class="term">byte locations</i>. A zbuf byte location has two parts, an <i class="term">offset </i>and a <i class="term">segment ID</i>.</p><dd><p class="Body"><a name="89467"> </a>An <i class="term">offset</i> is a signed integer (type <b class="keyword">int</b>): the distance in bytes to a portion of data in the zbuf, relative to the beginning of a particular segment. Zero refers to the first byte in a segment; negative integers refer to bytes in previous segments; and positive integers refer to bytes after the start of the current segment.</p><dd><p class="Body"><a name="89468"> </a>A <i class="term">segment ID</i> is an arbitrary integer (type <b class="keyword">ZBUF_SEG</b>) that identifies a particular segment of a zbuf. You can always use <b class="symbol_UC">NULL</b> to refer to the first segment of a zbuf.</p><dd><p class="Body"><a name="89472"> </a><a href="c-netapi3.html#89476">Figure 7-1</a> shows a simple zbuf with data organized into two segments, with offsets relative to the first segment. This is the most efficient addressing scheme to refer to bytes a, b, or c in the figure. <div class="frame"><h4 class="EntityTitle"><a name="89476"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 7-1: Zbuf Addressing Relative to First Segment (NULL)</font></a></h4><dl class="margin"><div class="Anchor"><a name="89505"> </a><img class="figure" border="0" src="images/c-netapi0.gif"></div></dl></div></p><dd><p class="Body"><a name="89509"> </a><a href="c-netapi3.html#89513">Figure 7-2</a> shows the same zbuf, but labelled with offsets relative to the second segment. This is the most efficient addressing scheme to refer to bytes d, e, f, or g in the figure.<div class="frame"><h4 class="EntityTitle"><a name="89513"><font face="Helvetica, sans-serif" size="-1" class="sans">Figure 7-2: Zbuf Addressing Relative to Second Segment</font></a></h4><dl class="margin"><div class="Anchor"><a name="89541"> </a><img class="figure" border="0" src="images/c-netapia1.gif"></div></dl></div></p><dd><p class="Body"><a name="89542"> </a>Two special shortcuts give the fastest access to either the beginning or the end of a zbuf. The constant <b class="symbol_UC">ZBUF_END</b> refers to the position after all existing bytes in the zbuf. Similarly, <b class="symbol_UC">ZBUF_BEGIN</b> refers to the position before all existing bytes. These constants are the only offsets with meanings not relative to a particular segment.</p><dd><p class="Body"><a name="89545"> </a>When you insert data in a zbuf, the new data is always inserted <i class="emphasis">before</i> the byte location you specify in the call to an insertion routine. That is, the byte location you specify becomes the address of the newly inserted data. </p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="89547">Creating and Destroying Zbufs </a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89549"> </a>To create a new zbuf, call <b class="routine"><i class="routine">zbufCreate</i></b><b>( )</b>. The routine takes no arguments, and returns a zbuf identifier (type <b class="keyword">ZBUF_ID</b>) for a zbuf containing no segments. After you have the zbuf ID, you can attach segments or otherwise insert data. While the zbuf is empty, <b class="symbol_UC">NULL</b> is the only valid segment ID, and 0 the only valid offset. </p><dd><p class="Body"><a name="89551"> </a>When you no longer need a particular zbuf, call <b class="routine"><i class="routine">zbufDelete</i></b><b>( )</b>. Its single argument is the ID for the zbuf to delete. The <b class="routine"><i class="routine">zbufDelete</i></b><b>( )</b> routine calls the free routine associated with each segment in the zbuf, for segments that are not shared by other zbufs. After you delete a zbuf, its zbuf ID is meaningless; any reference to a deleted zbuf ID is an error. <i class="i"><p class="table"><h4 class="EntityTitle"><a name="89554"><font face="Helvetica, sans-serif" size="-1" class="sans">Table 7-4: Zbuf Creation and Deletion Routines</font></a></h4><table border="0" cellpadding="0" cellspacing="0"><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="middle"><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="89558"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Call</font></b></div></th><td width="10"> </td><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="89560"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Description</font></b></div></th><td width="10"> </td></tr><tr><td colspan="20"><hr class="tablerule2"></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="89562"> </a><b class="routine"><i class="routine">zbufCreate</i></b><b>( )</b></div></td><td width="10"> </td><td colspan=1 rowspan=1><div class="CellBody"><a name="89564"> </a>Create an empty zbuf.</div></td><td width="10"> </td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="89566"> </a><b class="routine"><i class="routine">zbufDelete</i></b><b>( )</b></div></td><td width="10"> </td><td colspan=1 rowspan=1><div class="CellBody"><a name="89568"> </a>Delete a zbuf and free any associated segments.</div></td><td width="10"> </td></tr><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="middle"><td colspan="20"></td></tr></table></p></i></p></dl></dl><font face="Helvetica, sans-serif" class="sans"><h4 class="H4"><i><a name="89569">Getting Data In and Out of Zbufs</a></i></h4></font><dl class="margin"><dl class="margin"><dd><p class="Body"><a name="89571"> </a>The usual way to place data in a zbuf is to call <b class="routine"><i class="routine">zbufInsertBuf</i></b><b>( )</b>. This routine builds a zbuf segment pointing to an existing data buffer, and inserts the new segment at whatever byte location you specify in a zbuf. You can also supply a callback pointer to a free routine, which the zbuf library calls when no zbuf segments point to that data buffer. </p><dd><p class="Body"><a name="89572"> </a>Because the purpose of the zbuf socket interface is to avoid data copying, the need to actually copy data into a zbuf (rather than designating its location as a shareable buffer) occurs much less frequently. When that need does arise, however, the routine <b class="routine"><i class="routine">zbufInsertCopy</i></b><b>( )</b> is available. This routine does not require a callback pointer to a free routine, because the original source of the data is not shared.</p><dd><p class="Body"><a name="89574"> </a>Similarly, the most efficient way to examine data in zbufs is to read it in place, rather than to copy it to another location. However, if you must copy a portion of data out of a zbuf (for example, to guarantee the data is contiguous, or to place it in a data structure required by another interface), call <b class="routine"><i class="routine">zbufExtractCopy</i></b><b>( )</b> specifying what to copy (zbuf ID, byte location, and the number of bytes) and where to put it (an application buffer). <i class="i"><p class="table"><h4 class="EntityTitle"><a name="89579"><font face="Helvetica, sans-serif" size="-1" class="sans">Table 7-5: Zbuf Data Copying Routines</font></a></h4><table border="0" cellpadding="0" cellspacing="0"><tr><td colspan="20"><hr class="tablerule"></td></tr><tr valign="middle"><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="89583"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Call</font></b></div></th><td width="10"> </td><th rowspan="1" colspan="1"><div class="CellHeading"><b><a name="89585"> </a><font face="Helvetica, sans-serif" size="-1" class="sans">Description</font></b></div></th><td width="10"> </td></tr><tr><td colspan="20"><hr class="tablerule2"></td></tr><tr valign="top"><td colspan=1 rowspan=1><div class="CellBody"><a name="89587"> </a><b class="routine"><i class="routine">zbufInsertBuf</i></b><b>( )</b></div></td><td width="10"> </td><td colspan=1 rowspan=1><div class="CellBody"><a name="89589"> </a>Create a zbuf segment from a buffer and insert into a zbuf.</div></td><td width="10"> </td>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -