📄 zbuflib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/zbufLib.html - generated by refgen from zbufLib.c --> <title> zbufLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>VxWorks Reference Manual : Libraries</i></a></p></blockquote><h1>zbufLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>zbufLib</strong> - zbuf interface library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><i><a href="./zbufLib.html#zbufCreate">zbufCreate</a></i>( )</b> - create an empty zbuf<br><b><i><a href="./zbufLib.html#zbufDelete">zbufDelete</a></i>( )</b> - delete a zbuf<br><b><i><a href="./zbufLib.html#zbufInsert">zbufInsert</a></i>( )</b> - insert a zbuf into another zbuf<br><b><i><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a></i>( )</b> - create a zbuf segment from a buffer and insert into a zbuf<br><b><i><a href="./zbufLib.html#zbufInsertCopy">zbufInsertCopy</a></i>( )</b> - copy buffer data into a zbuf<br><b><i><a href="./zbufLib.html#zbufExtractCopy">zbufExtractCopy</a></i>( )</b> - copy data from a zbuf to a buffer<br><b><i><a href="./zbufLib.html#zbufCut">zbufCut</a></i>( )</b> - delete bytes from a zbuf<br><b><i><a href="./zbufLib.html#zbufSplit">zbufSplit</a></i>( )</b> - split a zbuf into two separate zbufs<br><b><i><a href="./zbufLib.html#zbufDup">zbufDup</a></i>( )</b> - duplicate a zbuf<br><b><i><a href="./zbufLib.html#zbufLength">zbufLength</a></i>( )</b> - determine the length in bytes of a zbuf<br><b><i><a href="./zbufLib.html#zbufSegFind">zbufSegFind</a></i>( )</b> - find the zbuf segment containing a specified byte location<br><b><i><a href="./zbufLib.html#zbufSegNext">zbufSegNext</a></i>( )</b> - get the next segment in a zbuf<br><b><i><a href="./zbufLib.html#zbufSegPrev">zbufSegPrev</a></i>( )</b> - get the previous segment in a zbuf<br><b><i><a href="./zbufLib.html#zbufSegData">zbufSegData</a></i>( )</b> - determine the location of data in a zbuf segment<br><b><i><a href="./zbufLib.html#zbufSegLength">zbufSegLength</a></i>( )</b> - determine the length of a zbuf segment<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library contains routines to create, build, manipulate, anddelete zbufs. Zbufs, also known as "zero copy buffers," are a dataabstraction designed to allow software modules to share bufferswithout unnecessarily copying data.<p>To support the data abstraction, the subroutines in this library hidethe implementation details of zbufs. This also maintains thelibrary's independence from any particular implementation mechanism,permitting the zbuf interface to be used with other buffering schemeseventually.<p>Zbufs have three essential properties. First, a zbuf holds asequence of bytes. Second, these bytes are organized into one or moresegments of contiguous data, although the successive segmentsthemselves are not usually contiguous. Third, the data within asegment may be shared with other segments; that is, the data may be in useby more than one zbuf at a time.<p></blockquote><h4>ZBUF TYPES</h4><blockquote><p>The following data types are used in managing zbufs:<dl><dt><b>ZBUF_ID</b><dd>An arbitrary (but unique) integer that identifies a particular zbuf.<p><dt><b>ZBUF_SEG</b><dd>An arbitrary (but unique within a single zbuf) integer that identifiesa segment within a zbuf. </dl><p></blockquote><h4>ADDRESSING BYTES IN ZBUFS</h4><blockquote><p>The bytes in a zbuf are addressed by the combination <i>zbufSeg</i>,<i>offset</i>. The <i>offset</i> may be positive or negative, and is simply thenumber of bytes from the beginning of the segment <i>zbufSeg</i>.<p>A <i>zbufSeg</i> can be specified as NULL, to identify the segment at thebeginning of a zbuf. If <i>zbufseg</i> is NULL, <i>offset</i> is theabsolute offset to any byte in the zbuf. However, it is moreefficient to identify a zbuf byte location relative to the <i>zbufSeg</i>that contains it; see <b><i><a href="./zbufLib.html#zbufSegFind">zbufSegFind</a></i>( )</b> to convert any <i>zbufSeg</i>, <i>offset</i>pair to the most efficient equivalent.<p>Negative <i>offset</i> values always refer to bytes before thecorresponding <i>zbufSeg</i>, and are usually not the most efficientaddress formulation in themselves (though using them may save yourprogram other work in some cases).<p>The following special <i>offset</i> values, defined as constants,allow you to specify the very beginning or the very end of an entire zbuf,regardless of the <i>zbufSeg</i> value:<dl><dt><b>ZBUF_BEGIN</b><dd>The beginning of the entire zbuf.<p><dt><b>ZBUF_END</b><dd>The end of the entire zbuf (useful for appending to a zbuf; see below). </dl><p></blockquote><h4>INSERTION AND LIMITS ON OFFSETS</h4><blockquote><p>An <i>offset</i> is not valid if it points outside the zbuf. Thus, toaddress data currently within an N-byte zbuf, the valid offsetsrelative to the first segment are 0 through N-1.<p>Insertion routines are a special case: they obey the usualconvention, but they use <i>offset</i> to specify where the new databegins after the insertion is complete. With regard to the originalzbuf data, therefore, data is always inserted just before the bytelocation addressed by the <i>offset</i> value. The value of thisconvention is that it permits inserting (or concatenating) data eitherbefore or after the existing data. To insert before all the datacurrently in a zbuf segment, use 0 as <i>offset</i>. To insert after allthe data in an N-byte segment, use N as <i>offset</i>. An <i>offset</i> of N-1inserts the data just before the last byte in an N-byte segment.<p>An <i>offset</i> of 0 is always a valid insertion point; for an empty zbuf,0 is the only valid <i>offset</i> (and NULL the only valid <i>zbufSeg</i>).<p></blockquote><h4>SHARING DATA</h4><blockquote><p>The routines in this library avoid copying segment data wheneverpossible. Thus, by passing and manipulating ZBUF_IDs rather thancopying data, multiple programs can communicate with greaterefficiency. However, each program must be aware of data sharing:changes to the data in a zbuf segment are visible to all zbuf segmentsthat reference the data.<p>To alter your own program's view of zbuf data without affecting otherprograms, first use <b><i><a href="./zbufLib.html#zbufDup">zbufDup</a></i>( )</b> to make a new zbuf; then you can use aninsertion or deletion routine, such as <b><i><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a></i>( )</b>, to add asegment that only your program sees (until you pass a zbuf containingit to another program). It is safest to do all direct datamanipulation in a private buffer, before enrolling it in a zbuf: inprinciple, you should regard all zbuf segment data as shared.<p>Once a data buffer is enrolled in a zbuf segment, the zbuf library isresponsible for noticing when the buffer is no longer in use by anyprogram, and freeing it. To support this, <b><i><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a></i>( )</b> requiresthat you specify a callback to a free routine each time you build azbuf segment around an existing buffer. You can use this callback to notifyyour application when a data buffer is no longer in use.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufLib.html#top">zbufLib</a></b>, <b><a href="./zbufSockLib.html#top">zbufSockLib</a></b>, <i>VxWorks Programmer's Guide: Network</i><p><hr><a name="zbufCreate"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>zbufCreate</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>zbufCreate</i>( )</strong> - create an empty zbuf</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>ZBUF_ID zbufCreate (void)</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine creates a zbuf, which remains empty (that is, it containsno data) until segments are added by the zbuf insertion routines.Operations performed on zbufs require a zbuf ID, which is returned bythis routine.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>A zbuf ID, or NULL if a zbuf cannot be created.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufLib.html#top">zbufLib</a></b>, <b><i><a href="./zbufLib.html#zbufDelete">zbufDelete</a></i>( )</b><hr><a name="zbufDelete"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>zbufDelete</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>zbufDelete</i>( )</strong> - delete a zbuf</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS zbufDelete ( ZBUF_ID zbufId /* zbuf to be deleted */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine deletes any zbuf segments in the specified zbuf, thendeletes the zbuf ID itself. <i>zbufId</i> must not be used after this routineexecutes successfully.<p>For any data buffers that were not in use by any other zbuf, <b><i><a href="./zbufLib.html#zbufDelete">zbufDelete</a></i>( )</b>calls the associated free routine (callback).<p></blockquote><h4>RETURNS</h4><blockquote><p><p>OK, or ERROR if the zbuf cannot be deleted.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufLib.html#top">zbufLib</a></b>, <b><i><a href="./zbufLib.html#zbufCreate">zbufCreate</a></i>( )</b>, <b><i><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a></i>( )</b><hr><a name="zbufInsert"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>zbufInsert</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>zbufInsert</i>( )</strong> - insert a zbuf into another zbuf</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>ZBUF_SEG zbufInsert ( ZBUF_ID zbufId1, /* zbuf to insert <i>zbufId2</i> into */ ZBUF_SEG zbufSeg, /* zbuf segment base for <i>offset</i> */ int offset, /* relative byte offset */ ZBUF_ID zbufId2 /* zbuf to insert into <i>zbufId1</i> */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine inserts all <i>zbufId2</i> zbuf segments into <i>zbufId1</i> at thespecified byte location.<p>The location of insertion is specified by <i>zbufSeg</i> and <i>offset</i>. Seethe <b><a href="./zbufLib.html#top">zbufLib</a></b> manual page for more information on specifyinga byte location within a zbuf. In particular, insertion withina zbuf occurs before the byte location specified by <i>zbufSeg</i> and <i>offset</i>.Additionally, <i>zbufSeg</i> and <i>offset</i> must be NULL and 0,respectively, when inserting into an empty zbuf.<p>After all the <i>zbufId2</i> segments are inserted into <i>zbufId1</i>, the zbuf ID<i>zbufId2</i> is deleted. <i>zbufId2</i> must not be used after this routineexecutes successfully.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>The zbuf segment ID for the first inserted segment,or NULL if the operation fails.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufLib.html#top">zbufLib</a></b><hr><a name="zbufInsertBuf"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>zbufInsertBuf</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>zbufInsertBuf</i>( )</strong> - create a zbuf segment from a buffer and insert into a zbuf</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>ZBUF_SEG zbufInsertBuf ( ZBUF_ID zbufId, /* zbuf in which buffer is inserted */ ZBUF_SEG zbufSeg, /* zbuf segment base for <i>offset</i> */ int offset, /* relative byte offset */ caddr_t buf, /* application buffer for segment */ int len, /* number of bytes to insert */ VOIDFUNCPTR freeRtn, /* free-routine callback */ int freeArg /* argument to free routine */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine creates a zbuf segment from the application buffer <i>buf</i>and inserts it at the specified byte location in <i>zbufId</i>.<p>The location of insertion is specified by <i>zbufSeg</i> and <i>offset</i>. Seethe <b><a href="./zbufLib.html#top">zbufLib</a></b> manual page for more information on specifyinga byte location within a zbuf. In particular, insertion withina zbuf occurs before the byte location specified by <i>zbufSeg</i> and <i>offset</i>.Additionally, <i>zbufSeg</i> and <i>offset</i> must be NULL and 0,respectively, when inserting into an empty zbuf.<p>The parameter <i>freeRtn</i> specifies a free-routine callback that runs whenthe data buffer <i>buf</i> is no longer referenced by any zbuf segments. If<i>freeRtn</i> is NULL, the zbuf functions normally, except that theapplication is not notified when no more zbufs segments reference <i>buf</i>.The free-routine callback runs from the context of the task that lastdeletes reference to the buffer. Declare the <i>freeRtn</i> callback asfollows (using whatever routine name suits your application):<pre> void freeCallback ( caddr_t buf, /* pointer to application buffer */ int freeArg /* argument to free routine */ )</pre></blockquote><h4>RETURNS</h4><blockquote><p><p>The zbuf segment ID of the inserted segment,or NULL if the operation fails.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufLib.html#top">zbufLib</a></b><hr><a name="zbufInsertCopy"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>zbufInsertCopy</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>zbufInsertCopy</i>( )</strong> - copy buffer data into a zbuf</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>ZBUF_SEG zbufInsertCopy ( ZBUF_ID zbufId, /* zbuf into which data is copied */ ZBUF_SEG zbufSeg, /* zbuf segment base for <i>offset</i> */ int offset, /* relative byte offset */ caddr_t buf, /* buffer from which data is copied */ int len /* number of bytes to copy */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine copies <i>len</i> bytes of data from the application buffer <i>buf</i>and inserts it at the specified byte location in <i>zbufId</i>. Theapplication buffer is in no way tied to the zbuf after this operation;a separate copy of the data is made.<p>The location of insertion is specified by <i>zbufSeg</i> and <i>offset</i>. Seethe <b><a href="./zbufLib.html#top">zbufLib</a></b> manual page for more information on specifyinga byte location within a zbuf. In particular, insertion withina zbuf occurs before the byte location specified by <i>zbufSeg</i> and <i>offset</i>.Additionally, <i>zbufSeg</i> and <i>offset</i> must be NULL and 0,respectively, when inserting into an empty zbuf.<p></blockquote><h4>RETURNS</h4><blockquote><p><p>The zbuf segment ID of the first inserted segment,or NULL if the operation fails.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufLib.html#top">zbufLib</a></b><hr><a name="zbufExtractCopy"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -