zbuflib.html
来自「Vxworks API操作系统和驱动程序设计API。压缩的HTML文件」· HTML 代码 · 共 776 行 · 第 1/3 页
HTML
776 行
<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.htm"><i>VxWorks API Reference : OS 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><a href="./zbufLib.html#zbufCreate">zbufCreate</a>( )</b> - create an empty zbuf<br><b><a href="./zbufLib.html#zbufDelete">zbufDelete</a>( )</b> - delete a zbuf<br><b><a href="./zbufLib.html#zbufInsert">zbufInsert</a>( )</b> - insert a zbuf into another zbuf<br><b><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a>( )</b> - create a zbuf segment from a buffer and insert into a zbuf<br><b><a href="./zbufLib.html#zbufInsertCopy">zbufInsertCopy</a>( )</b> - copy buffer data into a zbuf<br><b><a href="./zbufLib.html#zbufExtractCopy">zbufExtractCopy</a>( )</b> - copy data from a zbuf to a buffer<br><b><a href="./zbufLib.html#zbufCut">zbufCut</a>( )</b> - delete bytes from a zbuf<br><b><a href="./zbufLib.html#zbufSplit">zbufSplit</a>( )</b> - split a zbuf into two separate zbufs<br><b><a href="./zbufLib.html#zbufDup">zbufDup</a>( )</b> - duplicate a zbuf<br><b><a href="./zbufLib.html#zbufLength">zbufLength</a>( )</b> - determine the length in bytes of a zbuf<br><b><a href="./zbufLib.html#zbufSegFind">zbufSegFind</a>( )</b> - find the zbuf segment containing a specified byte location<br><b><a href="./zbufLib.html#zbufSegNext">zbufSegNext</a>( )</b> - get the next segment in a zbuf<br><b><a href="./zbufLib.html#zbufSegPrev">zbufSegPrev</a>( )</b> - get the previous segment in a zbuf<br><b><a href="./zbufLib.html#zbufSegData">zbufSegData</a>( )</b> - determine the location of data in a zbuf segment<br><b><a href="./zbufLib.html#zbufSegLength">zbufSegLength</a>( )</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,thus permitting the zbuf interface to be used with other buffering schemes.<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.<dt><b>ZBUF_SEG</b><dd>An arbitrary (but unique within a single zbuf) integer that identifiesa segment within a zbuf.</dl></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><a href="./zbufLib.html#zbufSegFind">zbufSegFind</a>( )</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 not usually the most efficientaddress formulation (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.<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. Therefore, the originalzbuf 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 <b>ZBUF_IDs</b> 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><a href="./zbufLib.html#zbufDup">zbufDup</a>( )</b> to make a new zbuf; then you can use aninsertion or deletion routine, such as <b><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a>( )</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><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a>( )</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>VXWORKS AE PROTECTION DOMAINS</h4><blockquote><p>Under VxWorks AE, this feature is restricted to the kernel protection domain. This restriction does not apply under non-AE versions of VxWorks. <p>To use this feature, include the following component:<b>INCLUDE_ZBUF_SOCK</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./zbufSockLib.html#top">zbufSockLib</a></b><p><hr><a name="zbufCreate"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>zbufCreate( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>zbufCreate( )</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>VXWORKS AE PROTECTION DOMAINS</h4><blockquote><p>Under VxWorks AE, you can call this function from within the kernel protection domain only. In addition, the returned ID is valid within the kernel protection domain only. This restriction does not apply under non-AE versions of VxWorks. <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><a href="./zbufLib.html#zbufDelete">zbufDelete</a>( )</b><hr><a name="zbufDelete"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>zbufDelete( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>zbufDelete( )</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><a href="./zbufLib.html#zbufDelete">zbufDelete</a>( )</b>calls the associated free routine (callback).<p></blockquote><h4>VXWORKS AE PROTECTION DOMAINS</h4><blockquote><p>Under VxWorks AE, you can call this function from within the kernel protection domain only. In addition, all arguments to this function can reference only that data which is valid in the kernel protection domain. This restriction does not apply under non-AE versions of VxWorks. <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><a href="./zbufLib.html#zbufCreate">zbufCreate</a>( )</b>, <b><a href="./zbufLib.html#zbufInsertBuf">zbufInsertBuf</a>( )</b><hr><a name="zbufInsert"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>zbufInsert( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>zbufInsert( )</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>VXWORKS AE PROTECTION DOMAINS</h4><blockquote><p>Under VxWorks AE, you can call this function from within the kernel protection domain only. In addition, all arguments to this function can reference only that data which is valid in the kernel protection domain. Likewise, the returned <b>ZBUF_SEG</b> is valid within the kernel protection domain only. This restriction does not apply under non-AE versions of VxWorks. <p></blockquote><h4>RETURNS</h4><blockquote><p><p>⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?